When organizing code reviews some time ago, when it came to code readability issues, many people’s first reaction was to add more comments. And I always feel that annotations can only be icing on the cake, not a gift in the snow. No amount of comments can change the fact that the logical organization of the code is chaotic. On the contrary, too many comments will increase the time to read the code.
Nothing is more useful than a well-placed comment; nothing messes up a module more than a jumbled comment; nothing is more destructive than a stale, misinformative comment
Comments are a necessary evil. Only when the expressiveness of the programming language is not enough, we need to use comments to explain the meaning of the code. The proper use of comments is to compensate for our failure to express intent in code. If you find yourself needing to write comments, think about whether you can express them in code.
Another fatal disadvantage of annotations is that they are not necessarily correct. When we see their comments when we modify other people's code, we have a great chance not to modify their comments. Over time, the meaning of the commented code has changed, but the comments have not been maintained along with the maintenance of the code.
1. Comments cannot beautify bad code
One of the common motivations for writing comments is the presence of bad code.
Clean and expressive code with a few comments is much easier to read and maintain than piecemeal and complex code with a lot of comments.
2. Use code to explain
For example, the following code, which one do you prefer to see:
3. Good Notes
Some comments are both necessary and beneficial. But the only really good comments are those that can be expressed without comments.
3.1 Legal information
3.2 Notes providing necessary information
3.3 Interpretation of intent
Sometimes annotations provide not only useful information about the implementation, but also the intent behind a certain decision.
3.4 Interpretation
Sometimes comments translate the meaning of some obscure parameter or return value into some readable form. Usually we try to make the parameter or return value itself express enough clearly, but if the return value or parameter is part of a standard library, we cannot modify the source code, then we can use comments to explain.
3.5 Warnings
Used to warn other programmers about the consequences of exceptions
3.6 ToDo Notes
ToDo is a kind of work that programmers think should be done, but for some reason has not been done yet.
3.7 Zoom in
Used to amplify the importance of something that seems irrational
3.8 java doc of public API
We often see this kind of annotation in JDK source code and spring source code
4. Bad comments
Most comments are bad comments. Often, bad comments are a support and an excuse for bad code, or a fix for a bad decision, basically equal to the programmer talking to himself.
4.1 Mumbling
It is pointless to add comments just because you think you should or because the process needs to add comments. If you decide to write comments, take the time necessary to make sure you write good ones.
4.2 Redundant comments
For example, the following code:
Comments cannot provide more information than the code itself.
4.3 Misleading Notes
If the comments written are not precise enough, they will mislead people who read the code.
4.4 Conforming Comments
The so-called rule that every function must have a Javadoc comment or every variable must have a comment, often makes the code messy, and as the code iterates, if the comment is not updated, it will mislead the understanding of the code.
4.5 Journaled comments
Someone will add a comment at the beginning of the module every time they edit the code. This kind of comment is like a kind of log recording every modification. An annotation like this:
4.6 Bullshit Notes
4.7 Position markers
Sometimes programmers like to mark a special place in the code, such as:
4.8 Notes after parentheses
4.9 Attribution and Signature
4.10 Commented out code
It is a bad practice to comment out the code directly. Those who maintain the program do not dare to delete the commented code, and the commented out code piles up, which will interfere with the reading of the code, which is not conducive to code maintenance and reading.
4.11 HTML comments
4.12 Non-local information
If you write a comment, make sure it describes the code closest to it.
4.13 Too much information
4.14 Non-obvious connections
The connection between the comments and the code they describe should be obvious, at least so that readers can look at the comments and code and understand what the comments describe.
4.15 Function header
Functions don't need much description, and a good name for a function is usually much better than a comment in the function header.
4.16 Javadoc in non-public code
Javadoc is very useful for public APIs, but it is cumbersome for code that is not counted as public use. It is not always useful to generate Javadoc pages for classes and functions in the system, and the extra formality requirements of javadoc comments are almost equivalent to stereotyped articles
summary:
- Do not use comments when you can use functions or variables to describe them.
- If you need to add comments, first consider whether you can reorganize the code and give a suitable function or variable name
- Comments are only added when necessary.