第二章 代码注释

注释

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

单行注释

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

// 好的写法
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
    }
}

所有的方法

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

所有的构造函数

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

所有包含文档化的对象

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