《编写可维护的JavaScript》学习笔记-第2章

第2章 注释

单行注释

• 独占一行的注释，用来解释下一行代码。这行注释之前总是有一个空行，且缩进层级和下一行代码保持一致。
• 在代码行的尾部的注释。代码结束到注释之间至少有一个缩进。注释（包括之前的代码部分）不应当超过当行最大字符数限制，如果超过了，就将这条注释放置于当前代码行的上方。
• 被注释掉的大段代码

// 好的写法,注释之前有空行，缩进也正确。
if（condition） {
    
    // 如果代码执行到这里，则表明通过了所有安全性检查
    allowed();
}

// 好的写法，代码和注释之间有间隔
var result = something + somethingElse; // 不应当取值为null

//好的写法
// if (condition) {
//     doSomething();
//     thenDoSomethingElse();
// } 

多行注释

Java风格的注释。第一行是/*，第二行是以*开始且和上一行的*保持左对齐，最后一行是*/

多行注释总是会出现在将要描述的代码段之前，注释和代码之间没有空行间隔。多行注释之前应当有一个空行，且缩进层级和其描述的代码保持一致。例如：

// 好的写法，注释之前有空行，星号后面有空格，缩进正确
// 不好的写法：代码尾部注释不要用多行注释格式
if (condition) {

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

添加注释的原则：在需要让代码变得更清晰时添加注释。难以理解的代码通常都应当加注释。

文档注释

来自于JavaDoc文档格式：多行注释以单斜线加双星号（/**）开始，接下来是描述信息，其中使用@符号来表示一个或多个属性。

确保对如下内容添加注释描述：

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

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

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