In current project development, code comments are like programmer's hair, less and less.
Especially in China, this phenomenon is not only common in small companies and small teams, but also in large companies and open source projects in large teams.
The picture above was taken by me in the source code of Ali's Druid project. DruidDataSource is a core class heavily used by Druid, which is very critical, but even for this key core class, there are no comments.
The absence of comments brings a lot of inconvenience to us when reading code. It's like throwing you a digital product with densely packed function buttons on it, but without giving you an instruction manual.
So why did the code comments disappear?
I try to summarize why:
1. The professional environment of domestic programmers is not friendly to adding comments
In this kind of environment in China, programmers are struggling in the depressing 996 every day. They are constantly doing various big and small jobs. They are very busy writing code normally, and adding comments further increases the workload. No one I like to add workload to myself.
Let's think about it, after writing a lot of code with great effort, and after repeated self-test and modification, it was finally adjusted, and my mind was already dizzy. How much thought would you have to write this comment at this time? Woolen cloth?
Think again, you may want to add comments to the code, and suddenly the product here pulls you into a meeting, or the operation there tells you that the requirements have changed, and the code you just wrote has to be changed... At this time , do you still have the idea of adding comments to the code?
In addition, it takes a lot of energy to write notes. Generally speaking, a good comment should be able to explain within a limited number of lines: what the code commented by it does, what kind of concept it is, and why this code was written.
Not to mention the trouble of writing comments, the key is that comments are not considered the workload of our programmers.
The job of a programmer is to implement business programs. The results of the work do not depend on how much code you have commented, nor whether your comments are good or bad. It only depends on whether your program is finished and whether it meets the requirements. What will go wrong online.
As for the comments, it rolls out of the KPIs for the programmer bros. How many companies can review code like Google? One of the BAT counts as one, which is almost meaningless.
Therefore, the poor environment of domestic programmers is the primary reason for the lack of code comments.
2. The way comments are viewed has changed
Java is an object-oriented language. Since its birth, the industry has continuously formulated countless specifications for Java.
In 2008, the book "Clean Code" - the Chinese name "The Way of Code Cleanliness" - a collection of these norms in Dacheng, appeared.
There is a concept in "The Way of Clean Code" that comments are a last resort to make up for the lack of code expression ability. If the code can be expressed clearly, then there is no need to write comments.
Even, the author of this book believes that writing comments needs to be described by the word failure, that is to say, if you write comments, it means that your code is not good enough, and your efforts to write good code have failed.
This concept has also been recognized by many big cows in the industry. Therefore, more and more people think that if the code is well written, there is no need to write comments.
If you are free, you can go to the fourth chapter of "The Way of Clean Code", which explains in detail the concept of annotations that is now accepted by many people in the industry.
Therefore, the view that "good code does not need comments" is also one of the reasons for the lack of comments.
3. The comments are not standardized, resulting in uneven quality
In many teams, there is no comment specification. There are no rules on how to comment and where to comment, and programmers are free to play.
This is troublesome, once the comment is written, it is very critical. because
Wrong comments are more harmful than no comments.
If the comments are poorly written, not only does the comment not play the role of helping to read the code, but it may also affect the reading of the code, and even lead people into a pit.
If there is no comment specification, it often happens that some people do well and others do poorly.
For example, some people add comments everywhere, i = i + 1; //Adding i to 1 even wants to add comments to such a simple code, which is a bit of a fart.
Some people wrote comments, but the requirements changed, and after the code was changed, the comments were too lazy to change. Or the person who changed the code was not the original author, and the newcomer didn't even realize that the comment should be changed after the change.
Therefore, if there is no specification, many programmers have no correct concept of comments, and the failure to write comments has caused complaints... Over time, no one likes to add comments.
How should comments be written?
After talking about so many reasons for not writing comments, I also want to explain my views on comments here.
Personally, I don't agree with "The Way of Clean Code" on comments. I read the code with good comments by myself, which directly saves more than 50% of the effort. The code with good comments reads like a cerebral thrombosis all year round, once it is opened by a leather stick, it is called a smooth.
For example, look at Netty's annotations:
/**
* A nexus to a network socket or a component which is capable of I/O
* operations such as read, write, connect, and bind.
* <p>
* A channel provides a user:
* <ul>
* <li>the current state of the channel (e.g. is it open? is it connected?),</li>
* <li>the {@linkplain ChannelConfig configuration parameters} of the channel (e.g. receive buffer size),</li>
* <li>the I/O operations that the channel supports (e.g. read, write, connect, and bind), and</li>
* <li>the {@link ChannelPipeline} which handles all I/O events and requests
* associated with the channel.</li>
* </ul>
*
* <h3>All I/O operations are asynchronous.</h3>
* <p>
* All I/O operations in Netty are asynchronous. It means any I/O calls will
* return immediately with no guarantee that the requested I/O operation has
* been completed at the end of the call. Instead, you will be returned with
* a {@link ChannelFuture} instance which will notify you when the requested I/O
* operation has succeeded, failed, or canceled.
*
* <h3>Channels are hierarchical</h3>
* <p>
* A {@link Channel} can have a {@linkplain #parent() parent} depending on
* how it was created. For instance, a {@link SocketChannel}, that was accepted
* by {@link ServerSocketChannel}, will return the {@link ServerSocketChannel}
* as its parent on {@link #parent()}.
* <p>
* The semantics of the hierarchical structure depends on the transport
* implementation where the {@link Channel} belongs to. For example, you could
* write a new {@link Channel} implementation that creates the sub-channels that
* share one socket connection, as <a href="http://beepcore.org/">BEEP</a> and
* <a href="http://en.wikipedia.org/wiki/Secure_Shell">SSH</a> do.
*
* <h3>Downcast to access transport-specific operations</h3>
* <p>
* Some transports exposes additional operations that is specific to the
* transport. Down-cast the {@link Channel} to sub-type to invoke such
* operations. For example, with the old I/O datagram transport, multicast
* join / leave operations are provided by {@link DatagramChannel}.
*
* <h3>Release resources</h3>
* <p>
* It is important to call {@link #close()} or {@link #close(ChannelPromise)} to release all
* resources once you are done with the {@link Channel}. This ensures all resources are
* released in a proper way, i.e. filehandles.
*/
public interface Channel extends AttributeMap, Comparable<Channel> {
Channel is a very core interface in Netty. You can directly understand why Netty created a Channel class by looking at the comments, and how you can play with the Channel class. These Netty explains clearly to you in the comments ,clear and direct.
Therefore, I think comments must be necessary, but there must be a standard and a degree.
From a practical point of view, our team has several standards that must be annotated:
1. Complex business logic
Business logic is associated with too many things or there are too many steps, or both, so few people will patiently and carefully read and straighten out the entire code line by line.
At this time, in the relevant classes of business logic implementation, it is necessary to clearly explain what the class is in the business logic implementation, why the class is designed in this way, and the corresponding business logic. And after refactoring the code, the comments must also be refactored.
2. Obscure Algorithms
Algorithms should also be annotated, especially those esoteric algorithms. It is impossible for everyone to be an algorithm expert, and they can understand the true meaning of algorithm implementation through code at once. Therefore, a note is also added here, generally explaining what algorithm is used, the source of this algorithm or the reference address of related articles.
3. Unconventional writing
Unconventional writing often has special circumstances and has to be done. For example, in order to get better performance; another example, in order to fix a bug, but do not want to make major changes to the code.
In short, unconventional writing is anti-pattern, anti-routine, and sometimes even violates the programmer's intuition. Like these practices, the reason for this implementation must be stated in the comments.
4. There may be pitfalls but there is no good solution for the time being
Sometimes, the requirements are difficult and complicated enough, and the time is urgent, and you can't think of a particularly good way to realize it right away. I can only think of a simple and crude plan for the time being, and try to survive first. Even in some places, the values of some variables are written to death to realize the needs of this issue first.
Like this, it is likely to dig a hole in the back. At this time, the comment must add the reason why it should be solved in this way, and it must also add //TODO, indicating that further modifications are required later.
5. About the interface, class and field of the core of the project
When working on a project, many core concepts in the requirements are likely to be mapped to the corresponding interfaces or entity classes. If you add clear annotations to these core interfaces and entity classes to indicate the corresponding business concepts, then later When maintaining a project, it is really getting twice the result with half the effort.
For example, in a batch scheduling system, we may have a variety of task concepts, some tasks need to limit the execution time, and some tasks do not need to limit the execution time, then in terms of implementation, there may be a LimitedTimeTask class corresponding to the limited time task, there is also an UnLimitedTimeTask class to correspond to tasks that do not need to limit the execution time. Then these two classes must be annotated to clearly write the corresponding business concepts.
If a specific concept is compound, consisting of multiple small concepts, but must be represented by an interface or a class, then it is likely to be realized, and fields must be used to map these small concepts, and these fields must also be added Notes explain the corresponding concepts.
In short, I personally understand that there must be comments, but they cannot be too extensive, and they must be added in a restrained and standardized way.
Finally, let's put it bluntly, my attitude towards comments is that, just like writing code, there must be specifications.
Let me tell the manager here, if you want everyone to write good comments, you can't just rely on the lofty words "you must write comments" to ask everyone. Without a specification, you can't totally blame the programmer for not commenting.