JavaScript 注释规范

总原则

1. **如无必要，勿增注释。**如果代码本身很清晰，就没必要增加注释。
2. **一目了然，容易看懂。**合理的注释、空行等排版，可以给代码增加美感。

什么时候需要添加注释

1. 涉及较复杂的逻辑，直接看代码，很难一目了然时。

2. 有借鉴第三方代码，需要说明时：

// 借鉴自 https://github.com/jquery/jquery/blob/master/src/core.js
function ready() {
}

3. 添加上注释，能让代码结构更清晰时：

init: function(selector, context, rootjQuery) {
    var match, elem, ret, doc;

    // Handle $(""), $(null), or $(undefined)
    if ( !selector ) {
        return this;
    }

    // Handle $(DOMElement)
    if ( selector.nodeType ) {
        this.context = this[0] = selector;
        this.length = 1;
        return this;
    }

    // The body element only exists once, optimize finding it
    if ( selector === "body" && !context && document.body ) {
        this.context = document;
        this[0] = document.body;
        this.selector = selector;
        this.length = 1;
        return this;
    }

    // Handle HTML strings
    if ( typeof selector === "string" ) {
        // ...
     }
}

注释的书写规范

1. 尽量用中文，除非用英文能更清晰的表达出来。
2. 含有中文的注释时，标点符号用中文全角。
3. 中英文夹杂时，英文与中文之间要用一个空格分开。
4. 注释标识符与注释内容要用一个空格分开：// 注释 与 /* 注释 */。

JSDoc 注释规范

• 当确定需要给类、方法、属性添加标准注释时，请遵循 JSDoc 规范。