The third reading note of "programming craftsmanship"

Chapter 5 notes

• Comments are very similar to comments. You can make comments as you like, but this is only because comments do not mean that these comments are correct.
• Annotations can separate excellent code from bad code, and separate rough, complex, and difficult logic from clear and friendly algorithms. However, we do not need to exaggerate the comments. If you have compiled really good code, the comments are like sugar on the cake.
• Good comments are a strategy to avoid code daunting. Comments themselves do not make bad code better.
• What is code annotation? From the syntax point of view, annotation is the original code block that the compiler will ignore. From the semantic point of view, annotation is the difference between the dirty and bright paths, you can use it to emphasize a special problem area, or the record media of the job header file.
• The target readers of comments are people rather than computers. If we want to improve the quality of comments, we must understand and satisfy what people really need when reading code.
• Code comments are not the only document you should put in the code. Annotations are neither a specification nor a design document nor an API reference. Annotation is a valuable form of documentation that is physically attached to the code. It is an internal document mechanism.
• There are various forms of annotations. Writing annotations is a subjective issue.
• Learning to write enough comments is far from enough. We should pay attention to quality rather than quantity.
• People who read your comments will also read your code, so document the code as much as possible instead of writing a lot of comments. You need to regard your code statement as the first-level annotation and make the code self-document.
• The compiled code does not actually need to be annotated, because each line of code can be self-explanatory. We should spend time writing code that does not require a large amount of comments.
  What should be included in the comment:
• Explain why, not how. You should change to several ways to describe why something needs to be written like this, or what role the next statement block will ultimately play. When we maintain a piece of code, the reasons for the existence of the Code are rarely changed, but the methods for implementing the Code are easily changed.
• Do not describe the code. Descriptive comments with no value are sometimes obvious, and there is no need to repeat code in English, unless you want to document an algorithm that is rather complex and incomprehensible without comments.
• Do not replace the code. When you discover that you are writing dense comments to explain your code, stop and think about whether there is a bigger problem to solve.
• Make sure the annotations are useful. A good comment is like a good code. It has the following features: 1. Record unexpected content; 2. Tell the truth; 3. Valuable; 4. Clear; 3. easy to understand.
• Avoid distractions. Annotations are used to describe the surrounding code, so we must avoid all factors that interfere with this function. Annotations should only increase value. Avoid the following annotations: 1. past Events; 2. do not include the code to be excluded in comments. ASCII technology; 4. the end of the code block should be on the same page with the beginning, and the code layout should be clear at the beginning and end of the block.
• Do not document bad code-rewrite the code.

  Good comments should have some principles for reference, as shown below:

• Consistency. All annotations should be clear and consistent. Select a specific layout method for your annotations, and always stick to this method.
• Clear block annotations. Consider the environment in which your comments may be viewed, and do not indulge in a highlighted editor. Clear comments should align the text up and down to make it easy to read after printing.
• Indent comments. Comments should not intercept the code or disrupt the logical process. Make the indent position of the comment consistent with the surrounding code.
• End comment. It is a good habit to keep blank between watching and code.
• Help you read the code. Usually comment above the code it describes, rather than below.
• Select a style with low maintenance costs. There is always a balance between beautiful source code and maintenance costs. Compared with getting ugly code, I prefer to spend some time on maintenance.
• Separator board. If your function is so large that you need some visual clues to indicate the beginning and end of the function, you should modify your code.
• Flag. Annotation can also be used as a sign embedded in the code.
• File Header comment. All source files should start with a comment block describing their content. The information should contain the object's purpose and the copyright statement describing ownership and copyright information. The header comment should not contain outdated information or contain the source file history that describes the changes made each time.
  There are two ways to write comments:
• First, use annotations to construct the code structure, and then fill in the code below each line of comments.
• First, write new code by hand and add necessary comments.
• Experienced programmers write code and write comments. Practice will tell you how many comments are correct.
• Placing a notice where errors are corrected is a common but controversial comment habit. Whether to add comments when making non-obvious changes to prevent others from introducing new errors when modifying the code in the future. There is still a debate on this issue.
• Annotations will be outdated, and all careless code will be outdated, resulting in many ugly defects and the loss of the original clean design. Annotations seem to be faster out of date than any other code, and they will be out of date with the code they describe.
• When you modify, add, or modify any code, modify, add, or modify related comments around it. Annotations must be simple enough to facilitate updates, otherwise they are easily outdated.
• If you find that a comment is incorrect or misleading, you should modify it as part of your code maintenance work.
• Annotations are not more important than the code they are labeled. You cannot use annotations to make bad code better. Your goal should be to write self-docized code that does not need to be annotated at all.
• Excellent programmers: 1. try to write only a small amount of good comments; 2. write comments explaining why; 3. concentrate on writing excellent code, rather than making too many comments; 4. it makes sense to write. Helpful annotations.
• Bad programmers: 1. do not tell the difference between a good comment and a bad comment; 2. write comments that explain how to do it; 3. I don't mind comments. They just make sense to themselves. 4. use many annotations to support bad code; 5. fill in the source file with redundant information.