《编写可维护的JavaScript》读书笔记(2)---注释

注释（Comments）

Opening a file without any comments may seem like a fun adventure, but when there are deadlines to meet , the task turns into torture.

单行注释

• 独占一行，解释下一行代码，注释之前总是有一个空行，且缩进层级和下一行代码保持一致；
• 在代码行尾注释。代码结束到注释之间至少有一个缩进。
• 被注释掉的大段代码

// 好的写法，注意文字与斜杠中间有一个空格
if (condition) {

    // 文字与下一层级的代码缩进一致，前面空一行
    allowed();
}

var result = something + somethingElse; // 注释与代码有一个缩进

// 好的写法，用于注释多行代码
// if (condition) {
//      dosomething();
//      thenDosomethingElse();
// } 

多行注释

/*
 * 另一断注释
 * 这段注释包含两行文本
 */

多行注释总是出现在要描述的代码段之前，注释和代码之间没有空行间隔。

多行注释之前应当有一个空行，符号* 和文字要有一个空格，与下层级的代码保持相同的缩进。

// 好的写法
if condition() {

    /*
     * 如果代码执行到这里
     * 说明通过了所有的安全性检测
     */
     allowed();
}

使用注释

• 当代码不够清晰时添加注释，而当代码很明了时不应当添加注释。
• 可以用单行注释、多行注释或者混用这两种注释。
• 当你写的代码有可能被其他的开发者认为是错误时，需要添加注释；尤其是你好心改了其他开发者的代码。

文档注释

• 所有的方法：应当对方法、期望的参数和可能的返回值添加注释描述。

• 所有的构造函数：应当对自定义类型和期望的参数添加注释描述。

• 所有包含文档化方法的对象

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