[GitHub] [kvrocks] PragmaTwice created a discussion: About code comments in kvrocks

["PragmaTwice (via GitHub)" <gi...@apache.org>]

GitHub user PragmaTwice created a discussion: About code comments in kvrocks

I have always believed that the code of kvrocks lacks comments, including the following aspects:

Firstly, many classes and functions in kvrocks lack documentation comments, making it difficult for developers to understand the meaning and important information of these classes and functions.

```c++
// what does the class Something do
// some important notice for developers to use Something 
class Something {
  // what does the function Something::f do
  // some important notice for developers to use Something::f
  // explaination of the input parameter a typed A
  // explaination of the return value typed B
  B f(A a);
}
```

Secondly, kvrocks lacks a unified comment identifier. Common identifiers include TODO and FIXME. TODO is used to express that there are some matters unresolved or unfinished in the code here, while FIXME is used to express that there are some issues in the code here that need to be fixed.

```c++
// TODO: blablabla
doSomething();

// FIXME: blablabla
doAnotherThing();
```

GitHub link: https://github.com/apache/kvrocks/discussions/1781

----
This is an automatically sent email for issues@kvrocks.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@kvrocks.apache.org

[GitHub] [kvrocks] PragmaTwice edited a discussion: About code comments in kvrocks

["PragmaTwice (via GitHub)" <gi...@apache.org>]

GitHub user PragmaTwice edited a discussion: About code comments in kvrocks

I have always believed that the code of kvrocks lacks comments, including the following aspects:

Firstly, many classes and functions in kvrocks lack documentation comments, making it difficult for developers to understand the meaning and important information of these classes and functions.

```c++
// what does the class Something do
// some important notice for developers to use Something 
class Something {
  // what does the function Something::f do
  // some important notice for developers to use Something::f
  // explaination of the input parameter a typed A
  // explaination of the return value typed B
  B f(A a);
}
```

Secondly, kvrocks lacks a unified comment identifier. Common identifiers generally include TODO and FIXME. TODO is used to express that there are some matters unresolved or unfinished in the code here, while FIXME is used to express that there are some issues in the code here that need to be fixed.

```c++
// TODO: blablabla
doSomething();

// FIXME: blablabla
doAnotherThing();
```

GitHub link: https://github.com/apache/kvrocks/discussions/1781

----
This is an automatically sent email for issues@kvrocks.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@kvrocks.apache.org

[GitHub] [kvrocks] torwig added a comment to the discussion: About code comments in kvrocks

["torwig (via GitHub)" <gi...@apache.org>]

GitHub user torwig added a comment to the discussion: About code comments in kvrocks

Comments can also improve the understandability of the codebase.
However, I'm a proponent of "right" comments explaining intricate algorithms/flow/decisions where the descriptive function/variable/function-parameters names don't help.

Useless, or "bad" comments are like:

```
// Server serves the incoming connections
class Server {...}

// Sets the name of something
// name is a new value for the name
void SetName(const std::string &name);

// Get the number of active connections
size_t GetActiveConnectionsNumber() const;
```

I agree that TODO and FIXME can be helpful (e.g. to find all TODOs in the project - some IDEs are able to do that).
I think sometimes TODO/FIXME can be converted into a created issue at the moment a developer decides to put that TODO/FIXME mark into the codebase.

GitHub link: https://github.com/apache/kvrocks/discussions/1781#discussioncomment-7122352

----
This is an automatically sent email for issues@kvrocks.apache.org.
To unsubscribe, please send an email to: issues-unsubscribe@kvrocks.apache.org