Writing maintainable JavaScript--javascript Coding Specification (iv)

Comment Line Comment

Single-line comments start with two slashes, ending with a line end

There are three ways to use a single-line comment:

• A comment on the exclusive line that explains the next line of code. There is always a blank line before this line of comments , and the indentation level is consistent with the next line of code.
• Comment At the end of the line. There is at least one indentation between the end of the code and the comment. Comments (including previous code sections) should not exceed the single-line maximum number of characters limit. If it is exceeded, place the comment above the current line of code.
• 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 multiline comments only when you need to annotate a long text

Multi-line comments

Multi-line annotations can wrap text across lines. It starts with/* and ends with */. Multi-line annotations can not only be used to wrap text across lines, it depends on you.

Recommended is a multi-line comment in Java style. 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 */. This kind of comment looks like this.

/*

* Another section of the note

* This comment contains two lines of text

*/

By making an asterisk on the left side of the note, you make the annotation clearer. Some Ides, such as Eclipse, will automatically insert these asterisks for you. There should be a space after the asterisk

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. Like a single-line comment, a multiline comment is preceded by a blank line, and the indentation level is consistent with the code it is describing.

Using annotations

When to add comments is a topic that programmers often argue about. 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.

Code that is difficult to understand is usually annotated.

Code that may be mistaken for error, need to add comments

Document comments

Document annotations are not part of JavaScript from a technical point of view, but they are a common practice. Document comments One of the most popular formats is from the Javadoc document grid: Multiline comments start with/**, followed by descriptive information, which uses the @ symbol to represent one or more properties. Take a look at the source code from the Yui example.

/** returns an object that contains all the properties of the provided object. The properties of the latter object override the properties of the previous object. Passing in a separate object creates a shallow copy of it (shallow copy). @method Merge@param {Object} is merged with one or more objects @return {object} A new merged object y.merge = function () {    //omitted to    return result;};

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

• All the methods

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

• All the constructors

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

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

Writing maintainable JavaScript--javascript Coding Specification (iv)