[Rule 2-1] annotations should be accurate and easy to understand to avoid ambiguity. Incorrect comments are not helpful but harmful.
[Rule 2-2] Write Code , modify the code, and modify the corresponding comments, to ensure the consistency between comments and codes.
annotations that are no longer useful must be deleted in a timely manner.
[Rule 2-3] The comment is a "prompt" for the code, not a document. The annotations in the Program should be simple and clear, and too many annotations
will be dazzling.
[Rule 2-4] clear statements without comments.
For example: I ++;/* I plus 1 */
additional comments
[Rule 2-5] for global data (global variables, constant definitions, etc) you must add comments.
[Rule 2-6] The annotations are in English. Do not use abbreviations in annotations, especially those that are not commonly used.
because not all compilers can display Chinese characters, comments may be messy when someone opens your code.
. Also, your code may not be read by anyone who understands Chinese.
[Rule 2-7] The comment location should be adjacent to the described code, which can be the same line as the statement or upstream, but
it cannot be placed below. Annotations for different domains in the same structure must be aligned.
[Rule 2-8] When the code is relatively long, especially when multiple nesting occurs, comments should be added at the end of some paragraphs for ease of reading
.
[Rule 2-9] the indent of the comment must be consistent with that of the Code.
[Rule 2-10] pay attention to "why" rather than "how" when commenting on code segments) ".
the description of how to make comments generally stays at the programming language level, rather than to illustrate the problem. Comments trying to explain "how to do"
generally do not tell us the intention of the operation, but comments indicating "how to do" are usually redundant.
[Rule 2-11] The unit of the value must be noted.
the comment should explain what the unit of a value means. For example, the unit of length must be in millimeters,
meters, or kilometers. The unit of time must be in minutes, seconds, or milliseconds.
[Rule 2-12] gives a comment on the variable range.
[Rule 2-13] provides a comment on a series of numbers, especially when writing underlying drivers (such as PIN numbers ).
[Rule 2-13] Comment on function entry and exit data.
function comments are discussed in more detail in the function chapter.