Absrtact: here is what I think is the common bad annotation style.
I believe that as programmers, as long as they write code, they will write and see the code comments written by others. Therefore, we often encounter comments like “a hundred flowers bloom and a hundred schools of thought contend”. 10 things programmers hate most, 0: write comments, 1: others don’t write comments.
As an old it person, after reading the code for so many years, I have read the comments for so many years. It can be said that good code does not necessarily have good comments, but bad code basically coexists with bad comments. Here’s what I think is the common bad annotation style. I hope it can help you in your future work. Ranked in no order:
1. The notes are marked with contact information, todo matters, questionnaire, demand link, etc. This style actually reflects the coding habit of engineers who did not consciously make good use of modern platform technology and stayed in the 1990s. In 2020, GIT software has become the preferred code hosting platform for software development. The best location for the requirements link and contact information of the questionnaire should be on git’s submission log, and todo matters should be managed by git’s issue. This note should be deleted when you see it. For example, the following two notes
2. There are some design contents on the notes. The biggest problem with these contents is that no one knows whether it is true or false, and no one knows whether it is complete. It’s a pity to delete it. What if it’s useful? Don’t delete it. It looks uncomfortable again. The biggest reason for this problem is that there is not a good place to host such documents in the team. In 2020, you can try GitHub’s pages platform.
3. Write how instead of why on the note. Everyone is very clear about this and agrees that it should not be. I won’t say more. Refer to the following example
4. Description of the use of the code, such as how to call the method, description of various parameters, and what exceptions will be thrown. For example, the following example is. If you have time to write such comments, you might as well write test cases and tell users how to use them through use cases.
5. The special description of an algorithm in the code is controversial. Strictly speaking, it is not a bad annotation. However, if this annotation is not strictly managed with the code (for example, if the code is changed, the annotation should be changed synchronously), then this annotation is not better. Therefore, although this is strictly a management reason, I prefer to write this comment on the submission log in 2020. How to put it? Use git’s submission to illustrate this problem. This submission only designs the non null judgment of a variable, and many people may submit it directly. Some people will also add comments on the code to explain why this non null judgment is made, but the author finally chose to explain this logic in the submission log, and wrote 20 lines (remove some personal signatures, and there are many effective lines). Imagine how much impact it will have on the reading of the code if you write these 20 lines into the code? But if you don’t write, it will bring problems to the subsequent maintenance.
This article is shared from Huawei cloud community “my comments, I decide”, original author: Zhou Daxian.
Click focus to learn about Huawei cloud’s new technologies for the first time~