注释

注释是代码中最常见的组成部分.它们是另一种形式的文档,也是程序员最后才舍得去写的

单行注释

• 独占一行的注释, 用来解释下一行代码.这行注释之前总是有一个空行,且缩进层级和下一代码保持一致
• 在代码行的尾部注释.代码结束到注释之间至少有一个缩进.注释(包括之前的代码部分),不应该超过单行最大注释,如果超过,这条注释就应该放置在当前代码行的上方
• 被注释掉的大段代码

// 好的写法 if (bol) {          // 这里是代码注释     test(); }   // 不好的写法: 注释之前没有空行 if (bol) {      // 这里是代码注释     test(); }  // 不好得写法: 错误的缩进 if (bol) {       // 这里是代码注释     test(); }    // 好的写法 var result = something + somethingElse; // somethingElse不应当为null    // 不好的写法: 代码和注释之间没有空格 var result = something + somethingElse;// somethingElse不应当为null  // 好的写法 // if (bol) {   //     test(); // }   // 不好的写法: 应该使用多行注释 // 接下来的有点难 // 我来解一下 // 先这样 // 然后那样 // 然后再这样 if (bol) {       test(); } 

多行注释

它以/*开始,以*/结束

var result = something + somethingElse;// somethingElse不应当为null// 好的写法 if (bol) {           /*     * 这个是一个多行注释     * 这个是第二行     */     test(); }   // 不好的写法: 注释前没有空行 if (bol) {       /*     * 这个是一个多行注释     * 这个是第二行     */     test(); }  // 不好的写法: 星号后没有空格 if (bol) {           /*     *这个是一个多行注释     *这个是第二行     */     test(); }    // 不好的写法: 错误的缩进 if (bol) {        /*  *这个是一个多行注释  *这个是第二行  */     test(); }   // 不好的写法: 行尾不适合使用多行注释 var result = something + somethingElse; /* somethingElse不应当为null */ 

使用注释

何时添加注释是程序员经常讨论的一个话题. 一种同行的指导原则是,当代码不够清晰的时候添加注释,而当代码很明了的时候不应当添加注释.

// 不好的写法 // 初始化count var count = 10;   // 好的写法 // 改变这个值可能会让它变成青蛙 var count = 10; 

难于理解的代码

难于理解的代码应该加上注释.根据代码的用途,你可以用单行注释/多行注释,或者混用两种注释.关键是让其他人更容易读懂这段代码

// 好的写法 if(mode){          /*      * 当mode为2时(原型到原型,对象到对象),这里只递归执行一次      * 用来执行原型到原型,对象到对象的都合并操作      * 将会被挂起,在合适的时机执行      */     if(mode === 2) {         Y.mix(...)     } } 

可能被误认为是错误的代码

while (element && (element = element[axis])){  // 提示: 赋值操作     if( (all || element[TAG_NAME]) && (!fn || fn(element))){         return element;     } } 

这个例子中,开发者在while循环控制条件中使用了一个赋值运算符.这不是一种标准的用法,并常常被检测工具认为有问题的.如果你对这个代码不熟悉,误以为是错误,加上了注释,就不会有这种误解了

浏览器特性hack

var ret = false;  if( !needle || !element || !needle[NODE_TYPE] || !element[NODE_TYPE]) {     ret = false; } else if (element[CONTAINS]) {     // 如果needle不是ELEMENT_NODE时, IE和Safari 下会有错误     if(Y.UA.opera || needle[NODE_TYPE] === 1){         ret = element[CONTAINS](needle);     }else{         ret = Y_DOM._bruteContains(element, needle);     } } // ....省略 

文档注释

从技术的角度讲, 文档注释并不是JavaScript的组成部分,但它们是一种普遍的实践

/* * 这个函数是用来测试文档注释的 * 这个函数是有几个参数 * 一个是这个,一个是哪个 * @method test * @params {String}  一个文字 * @params {Object}  一个对象 * @return {Object}  返回一个对象 */ var test = function (message, obj) {     return {         message: message,         obj: obj     } } 

所有的方法

• 应当对方法,期望的参数和可能返回的返回值添加注释描叙

所有的构造函数

• 应当对自定义类型和期望的参数添加注释描叙

所有包含文档化的对象

• 如果一个对象包含一个或者多个附带文档注释的方法,那么这个对象也应当适当地针对文档生成工具添加文档注释