JavaScript 注释规范

总原则

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

什么时候需要添加注释

1. 涉及较复杂的逻辑，直接看代码，很难一目了然时。
2. 添加上注释，能让代码结构更清晰时：

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

    // 处理 $(""), $(null) 与 $(undefined)
    if ( !selector ) {
        ...
    }

    // 处理 $(DOMElement)
    if ( selector.nodeType ) {
        ...
    }

    // 处理 $('String')
    if ( typeof selector === "string" ) {
        ...
     }
}

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

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

文件注释

每个源码文件的开头，推荐写上作者名称，比如：

/* @author 玉伯 <lifesinger@gmail.com> */

如果某个模块最初不是你开发，但后续做出了大量贡献时，可以添加到 contributors 上：

/**
 * @author 玉伯 <lifesinger@gmail.com>
 * @contributors John Resig <jresig@gmail.com> 
 */

有多个 author 或 contributors 时，用逗号加空格添加到后面就好：

/**
 * @contributors John Resig <jresig@gmail.com>, 玉伯 <lifesinger@gmail.com>
 */

注释书写规范

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

JSDoc 注释规范

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