Abstract: Here are some common bad annotation styles.

I believe that as programmers, as long as you write code, you will write and see others write code comments. As a result, we often encounter comments like “let a hundred flowers blossom and a hundred schools of thought contend”. 10 things programmers hate the most 0: Writing comments 1: Others don’t write comments

As an old IT guy, I’ve seen so many years of code, and I’ve seen so many years of comments. It can be said that good code does not necessarily have good comments, but bad code and bad comments basically coexist. Here are some common bad annotation styles that I think are helpful for you in your future work. In no particular order:

1. Notes with contact information, TODO items, list of requirements links, etc. This style reflects the inability of engineers to take advantage of modern platform technology and the coding habits of the 1990s. In 2020, Git class software has been the preferred code hosting platform for software development, the best place for links and contact information of problem sheet requirements should be on Git’s submission log, and TODO items should be managed using Git’s Issue. Such comments should be deleted as soon as they are seen. For example, the following two comments

2. Comments with some design content. The biggest problem with these contents is that no one knows if they are true or false, and no one knows if they are complete. It’s a pity to delete them, but what if they are useful? I don’t think so. It looks uncomfortable. The biggest reason for this problem is that there is not a good place within the team to host such documents. In 2020, try Github’s Pages platform.

3. Write how, not why, in comments. This is very clear to everyone, agreed that should not be. Without further ado, refer to the following example

4. Instructions on how to use the code, such as how the method is called, arguments, and what exceptions will be thrown. Take the following example. When you have time to write such comments, you might as well write test cases that tell users how they should be used.

5. A special description of an algorithm in the code is controversial. Strictly speaking, it is not a bad comment. So while this is strictly an administrative reason, in 2020, I would recommend putting comments like this in the commit log. How can I put it? Git commits only one variable to a non-null judgment. Many people would have submitted it directly. Some people would have commented on the code to explain why the non-null judgment was made, but they chose to explain the logic in the commit log. That’s 20 lines of code (a lot, if you strip out some personal signatures). Imagine the impact of putting those 20 lines into your code. However, if you do not write it, it will cause problems for the maintenance behind.

This article is shared from huawei cloud community “My notes my master”, the original author: Zhou Da Xianren.

Click to follow, the first time to learn about Huawei cloud fresh technology ~