Basic Requirements for outstanding comments

Source: Internet
Author: User

[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.

Contact Us

The content source of this page is from Internet, which doesn't represent Alibaba Cloud's opinion; products and services mentioned on that page don't have any relationship with Alibaba Cloud. If the content of the page makes you feel confusing, please write us an email, we will handle the problem within 5 days after receiving your email.

If you find any instances of plagiarism from the community, please send an email to: info-contact@alibabacloud.com and provide relevant evidence. A staff member will contact you within 5 working days.

A Free Trial That Lets You Build Big!

Start building with 50+ products and up to 12 months usage for Elastic Compute Service

  • Sales Support

    1 on 1 presale consultation

  • After-Sales Support

    24/7 Technical Support 6 Free Tickets per Quarter Faster Response

  • Alibaba Cloud offers highly flexible support services tailored to meet your exact needs.