Second, the note

2.1 Single-line comment

The single-line comment starts with two slashes and ends at the end of a line.

There are three ways to annotate a single line:

(1) A comment that is exclusive to the line that explains the next line of code. This line of comments always has a blank line before it, and the indent level is consistent with the next line.

(2) Comment at the end of the line of code. There is at least one indentation between the end of the code and the comment. Comments (including the previous Code section) should not exceed the single-line maximum character limit and, if exceeded, place the comment above the current line of code.

(3) A large piece of code that is commented out (many editors can comment out multiple lines of code in bulk).

A single-line comment should not appear as a continuous multiline comment unless you comment out a large piece of code. Use multiple lines of comments only when you need to annotate a long text.

//good wording.if(condition) {//If the code executes here, it means that all security checks are passeddosomething ();}//bad notation: No blank lines before commentsif(condition) {//If the code executes here, it means that all security checks are passeddosomething ();}//bad notation: the wrong indentationif(condition) {//If the code executes here, it means that all security checks are passeddosomething ();}//good wording.varresult = something + somethingelse;//SomethingElse should not take a value of NULL//bad notation: There is no interval between code and commentsvarresult = something + somethingelse;//SomethingElse should not take a value of NULL//good wording.//if (condition) {//dosomething ();// }//bad writing: You should use multiple lines of comments here//The next piece of code is very difficult, so let me explain in detail//The purpose of this code is to first determine whether the condition is true//It only happens when it's true .//multiple functions are calculated over the entire session life cycle//This value can be modified.if(condition) {//If the code executes here, it means that all security checks are passeddosomething ();}

2.2 Multi-line comments

Multi-line annotations can wrap text across lines. It starts with/* and ends with */.

Java-style annotations contain at least three lines: the first line is/*, the second line is left-aligned with the * start and the previous row, and the last line is */.

A multiline comment always appears before the code snippet that will be described, and there is no blank line interval between the comment and the code. As with a single-line comment, there should be a blank line before the multiline comment, and the indentation level is consistent with the code it describes.

//good wording.if(condition) {/** If this line of code executes here * The description passes all security checks*/dosomething ();}//bad notation: No blank lines before commentsif(condition) {/** If this line of code executes here * The description passes all security checks*/dosomething ();}//bad notation: There are no spaces behind the asteriskif(condition) {/** If this line of code executes here * The description passes all security checks*/dosomething ();}//bad notation: the wrong indentationif(condition) {/** If this line of code executes here * The description passes all security checks*/dosomething ();}//Bad writing: code trailer comments do not use multi-line annotation stylevarresult = something + somethingelse;/*SomethingElse should not take a value of NULL*/

2.3 Using annotations

A common guideline is to add comments when the code is not clear enough, and you should not add comments when the code is clear. For example, the note is superfluous.

Initialize Count

var count = 10;

Because the operation of initializing count in the code is obvious. The comment does not provide any other valuable information. In other words, if the value 10 has some special meaning and cannot be seen directly from the code, there is no need to add a comment.

Changing this value may turn it into a frog.

var count = 10;

If you do not add a comment, you modify the value of Count to become a frog, it will be confusing.

Therefore, one of the principles of adding annotations is to add comments when you need to make your code clearer.

2.3.1 Hard to understand code

Code that is difficult to understand is usually annotated. Depending on the purpose of your code, you can make single-line comments, multiple lines of comments, or mix the two annotations. The key is to make it easier for other people to read this piece of code.

2.3.2 code that may be mistaken for errors

Another good time to add comments is when a contemporary code appears to be wrong. In team development, there is always a good developer who is trying to edit the code and find someone else's error code and fix it immediately. Sometimes this code is not the source of the error, so the "fix it" error often creates other errors because this modification should be traceable. When you write code that might be considered wrong by another developer, you need to add a comment.

2.3.3 Browser features hack

JavaScript programmers often write inefficient, indecent, and downright dirty code that allows a low-level browser to work properly. In fact, this situation is a special "code that may be mistaken for error": This hack code that does not manifest itself as a browser feature may imply some errors.

2.4 Documentation Comments

Javadoc Document Format: Multiline comments start with a single slash plus double Star (/**), followed by descriptive information, which uses the @ symbol to represent one or more properties.

/**/varfunction  (x, y     ) {return x + y;}

When working with document annotations, you should make sure that you add comments to the following.

(1) All the methods

You should add a comment description to the method, expected parameters, and possible return values.

(2) All constructors

You should add a comment description to the custom type and expected parameters.

(3) All objects that contain a documented method

If an object contains one or more methods that include a document comment, the object should also add a document comment to the document generation tool appropriately.

Of course, the format and usage of annotations are ultimately determined by the document generation tool that you choose.

Second, the note