Develop good habits 13 tips on code comments

The following 13 tips Make your code easy to understand and maintain for a long time.

1. Comment on different levels of code

For different levels of code blocks, you must use a unified method for comments. For example:

Each class must contain a brief description of the author and the last modification time.

Each method must contain the purpose, function, parameters, and returned results of this method.

When you are in a team, it is very important to adopt a set of annotation standards. Of course, using a comments Convention and tool that everyone recognizes (such as C # xml comments and Java javadoc) can push this task to a certain extent.

2. Use paragraph comments

First, the code block is divided into multiple "sections", each section executes a single task, and then adds comments before each "section" starts, tell the person who reads the code what the next code is

 

// Check that all records are correct Foreach (record in Records) { If (Rec. checkstatus () = status. OK) { ... } } // Start processing now Context CTX = new applicationcontext (); CTX. begintransaction (); ...

 

3. Align the comment line

For codes with comments written at the end of a line, the comments line should be aligned to facilitate reading.

Some developers use tabs to align annotations, while others use spaces to align annotations. Because tabs are different in different editors and integrated development environments, the best way is to use spaces to align comment rows.

 

Const max_items = 10; // maximum number of packets Const mask = 0x1f; // mask bit TCP

 

4. Do not insult the reader's wisdom

Avoid unnecessary comments, such

 

If (A = 5) // if A is equal to 5 Counter = 0 // set counte to 0

 

This is not just a waste of time writing useless comments, but also distracting readers.

5. Be polite

Avoid comments without courtesy, such as "note that some stupid users will enter a negative number", or "correct the side effects of silly code written by cainiao engineers ". Such comments are not good for code writers. At the same time, you will never know who will read these comments in the future. Your boss, A customer or a stupid engineer who has just been counted by you.

6. straightforward

Do not write too much nonsense in comments. Avoid selling ASCII art in comments, writing jokes, making poems, and being too lengthy. In short, annotations are kept simple and straightforward.

7. Use a unified style

Some people think that comments should be understandable to non-programmers. Others think that comments are only intended for programmers. In any case, as stated in successful strategies for commenting code, the most important thing is that the annotation style needs to be unified and always oriented to the same readers. In my opinion, I doubt whether non-programmers will read the code, so I think the comments should be written for programmers.

8. Use special labels internally

When you work in a team, using a set of consistent labels can help different programmers communicate. For example, many teams use the "Todo" label to indicate a piece of unfinished code.

Tag comments do not explain the code. They seek attention or pass information. However, if you use this technology properly, remember to follow up this code and complete the task of passing the label.

 

Int estimate (int x, int y) { // Todo: implement the calculations Return 0; }

 

9. Add comments while writing code

Add comments when you write code and remember it. If you do not add comments after the project is completed, you will get twice the result. "I don't have time to write comments", "My time is tight", and "The project has been delayed" are common excuses for not writing comments. Some engineers find that the best solution is "comment first ". For example:

 

Public void processorder () { // Make sure the products are available // Check that the customer is valid // Send the order to the store // Generate Bill }

 

10. Think of yourself as a comments reader (in fact)

When you are writing comments to the code, you should not only consider the developer who maintains your code in the future, but also imagine if you are the author of the comments. Phil haack once said:

 

"Once a line of code is knocked into the file, you have to start to maintain that line of code ."

 

Therefore, we ourselves are the first beneficiaries (or victims) of good (or bad) comments ).

11. Update comments when updating code

If the comments are not updated with the code modification, the comments will be meaningless. Code and comments must be synchronized. Otherwise, comments only make the code maintenance developer more painful. Note that some refactoring tools will automatically update the code, but the comments are not automatically updated, so the comments will expire naturally.

12. The code with good readability is the golden rule of Annotation

For many developers, a basic principle is to allow the code to describe itself. Although some people suspect that this is a movement advocated by programmers who do not like to write comments, codes that do not need to be interpreted have great advantages, these codes are easier to understand and even unnecessary for annotations. For example, in my article fluid interfaces, we will show you what code is clear without explanation.

In this example, annotations become unnecessary as they violate the 4th skills. To write readable code, you need to use the appropriate naming method (described in the classic ottinger's rules) to ensure proper indentation and adopt the encoding style guidance. If the Code does not follow this technique, the comments look like an apology for your own bad code.

13. share these skills with your colleagues

Although we have learned from 10th tips that we are the beneficiaries of good comments, these skills are very helpful for all developers, especially when the entire team has the same consensus. Therefore, sharing these skills with your colleagues allows us to write code that is easier to understand and maintain.

 

Calculator calc = new calculator (); Calc. Set (0 ); Calc. Add (10 ); Calc. Multiply (2 ); Calc. Subtract (4 ); Console. writeline ("Result: {0}", Calc. Get ());

 

(Author: Jos é M. Aguilar Translation: timm Martin Source: devtopics)