10 code comments and formatting best practices

Code comments and formatting are related to the readability of code, and code readability is critical to code maintainability, so some small details of programming can help improve code maintainability. This article lists some good examples of code comments and formatting.

First, Comments

Annotations are part of the code, and their importance is obvious. Code that lacks comments can be said to be useless, although it is suggested to use self-documenting code, but we think self-documenting + code documentation is the best.

1. Use annotations only when necessary

That is, you do not need to use annotations for each row
Java code

1. int count = 0; //assigns the initial value of Count to 0 (?!?)

However, the lack of annotations can increase maintenance difficulty, so the naming of variables and methods should be easy to understand
Java code

2. int  s = sqrt (v1)  + v2 / v3 + fread (s).  getchar (0 )   //(?!?)   
4. list<int> getval (int val, int len, String op) //(?!?)

2. The wrong comment is better than no comment and should be avoided as far as possible.

3. Write comments for important and no self-documenting variables.

4. Write comments for public methods (such as Javadoc Declaration), of course, these comments should be really necessary to add.

5. Notes like "Understand", "todo" may be important for the day, but should be deleted later.

second, the format of

There are many development tools, such as Maven Checkstyle, that provide code formatting, and formatting can be done automatically when the code is saved, but these formats do not necessarily conform to the company's formatting rules, so you set them before you use them.

1. Use a consistent bracket format. Parentheses are usually added to the end of the current line or to the header of a new line, select an Add method, and keep the same formatting across all lines of code.

2. Use a consistent blank line. Blank lines are used to separate code and semantic groups to improve code readability. For example, using 3 lines of blank lines to represent the end of a method, no blank lines, or a blank line between each line of code, is not conducive to good code aesthetics.

3. Note the first line indent. Proper indentation is as important as parentheses and empty lines for semantic blocks.

4. Limit the number of characters per line to improve readability. Most programmers recognize a limit of 80 or so.

5. Use a consistent space, usually following these cases to use a space:

Java code

2. //Operator and variable
4. A + = B, c = 0; (A = = b)
8. //Statement keyword and parentheses
10. if (value) {, public class A {
14. //Cycle ";" After
16. for (int i = 0; i < length; i++)
20. //between type and variable
22. (int) value, (String) value
    

10 code comments and formatting best practices