编写可维护的JavaScript-注释

注释是代码中最常见的组成部分，他们是另一种形式的文档，也是很重要的一部分。

JavaScript支持两种不同类型的注释：单行注释和多行注释。

1. 单行注释

1
// 这是一个单行注释

很多人喜欢在双斜线后敲入一个空格，用来让注释文本有一定的偏移，当行注释有三种使用方法。

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

单行注释不应当以连续多行注释的形式出现，除非你注释掉一大段代码。只有当需要注释一段很长的文本时才需要使用多行注释。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
// 好的写法
if (condition)  {
  
    // 如果代码执行到这里，则表明通过了所有安全性检查
    allowed();
}

// 不好的写法，注释之前没空行
if (condition)  {
    // 如果代码执行到这里，则表明通过了所有安全性检查
    allowed();
}

// 不好的写法，错误的缩进
if (condition)  {
  
// 如果代码执行到这里，则表明通过了所有安全性检查
    allowed();
}

//  好的写法
var result = something + somethingElse;    // somethingElse不应当取值为null

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

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

2. 多行注释

多行注释可以包括跨行文本，它以 /* 开始，以 / 结束。在这里推荐Java风格的注释写法，其注释风格至少包括三行：第一行是 / ，第二行是以 * 开始且和上一行的 * 保持左对齐，最后一行是以 */ 结束。

1
2
3
4
/*
 * 另一段注释
 * 这是注释包含两行文本
 */

和单行注释一样，多行注释之前应当有一个空行，且缩进层级和其描述的代码保持一致。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
// 好的写法
if (condition) {
    
    /*
     * 如果代码执行到这里
     * 说明通过了所有的安全性检测
     */
    allowed();
}

// 不好的写法：注释之前无空行
if (condition) {
    /*
     * 如果代码执行到这里
     * 说明通过了所有的安全性检测
     */
    allowed();
}

// 不好的写法：星号后没有空格
if (condition) {
    
    /*
     *如果代码执行到这里
     *说明通过了所有的安全性检测
     */
    allowed();
}

// 不好的写法：错误的缩进
if (condition) {
    
/*
 * 如果代码执行到这里
 * 说明通过了所有的安全性检测
 */
    allowed();
}

// 不好的写法，代码尾部注释不要使用多行注释
var result = something + anything;    /*something不应当取值为null*/

3. 使用注释

何时添加注释是程序员经常争论的一个话。一种通知的原则是，当代码不够清晰时添加注释，而当代码很明了时不应当添加注释。其中当某一代码块难以理解时应当添加注释，当某一段代码容易被人误解时也应当添加注释，当需要照顾其他浏览器而书写的比较低级，肮脏的代码时也需要加以注释。

1
2
3
while(element = element[axis]) {    // 提示：赋值操作
      ......
}

如上代码所示，在条件框中进行赋值操作确实存在疑虑，因为大多数情况下条件框中都是比较运算符 == 而不是赋值运算符 = ，所以此处会让后续读者认为这是原作者的错误而修改它，作者在这里添加一条注释就可告诉后来人此处正确的情况就是赋值语句，没有出错。

4. 文档注释

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

1
2
3
4
5
6
7
8
9
/**
 * 如果需要深拷贝，请使用 'clone()'
 * @method merge
 * @param {object} 被合并的一个或多个对象
 * @return {object} 一个新的合并后的对象
 **/
function merge (object xxx) {
    return xxx;
}

应当对以下情况使用文档注释：

  • 所有的方法：应当对方法，期望的参数和可能的返回值加注释描述。
  • 所有的构造函数：应当对自定义类型和期望的参数添加注释描述。
  • 所有包含文档化方法的对象。