如何写代码注释 - How to Comment Your Code （学习笔记）

Reference：

How to Comment Your Code Like a Pro: Best Practices and Good Habits (elegantthemes.com)

13 Tips to Comment Your Code (devtopics.com)

 

Tenets:

Make them brief ​

Keep them relevant ​

Use them liberally, but not to excess

 

Header Comment:

1. The name and brief introduction of your project can be showed in the main file of your code.

2. Simple explanations of what to expect in that file.

3. Version number is expected to be listed at the very top.

 

In-Line Comment:

1. Comment each code block, using a uniform for each level. For example:

   • For each class, include a brief description, author and date of last modification

   • For each method, include a description of its purpose, functions, parameters and result

2. Add a comment at the beginning of each block to instruct the reader on what is about to happen.

3. Align the consecutive trailing comments so that they will be easy to read.

4. Do not do line-by-line comments like the code below:

   （It should be done before or after the a piece of code.）

   function sourceCodeComment () { //calls a function
       var comment = document.getElementbyID("Code Comment").value; // declares a variable
       if (comment != null && comment != '') {  
         // starts an if statement to evaluate if there's a comment
         return console.log("Thank you for your comment.") //prints a string to the console
       }
   }    

5. Avoid obviously needless comments like:

   if (a==5)           // if a equals 5
       counter = 0;    // set the counter to zero

      6. If there is something that doesn't work and you know other people will likely try in the future, it's OK to make some warnings in the comment.

      7. Be polite. (Don't use rude comments like, "Notice the stupid user……")

      8. Don't write more than what is needed to convey the idea. Keep the comments simple and direct. What is more than that should go into the documentation.

      9. Keep the comments in a consistent style.

    10. Some placeholders can be used in the file as a sign to help yourself return there, or as an example to someone as an explanation.

    11. Comment code while writing it to save your time and make you clear when writing your code.

    12. Write comments as if they were for you (in fact, they are).

As soon as a line of code is laid on the screen, you're in maintenance mode on that piece of code.

                                                                                                                      ---- Phil Haack

    13. Don't forget to update comments when you update the code.

 

 

Conclusion:

        A good code comment will not only make your job easier in the future, but will also help out anyone who comes after you. It may take much practice day in and day out to get a good command of this skill. However, practice makes perfect.