《编写可维护的 JavaScript》编程风格 - 第 2 章 注释

编程风格 - 第 2 章 注释

《编写可维护的 JavaScript》—— Nicholas C. Zakas

打开一个没有任何注释的文件就好像趣味冒险，但如果给你的时间有限，这项任务就变成了折磨。
适度的添加注释可以解释说明代码的来龙去脉，其他开发者就可以不用从头开始读代码，而是直接去读代码的任意部分。

编程风格通常不会包含对注释的风格约定，但我认为从注释的作用即可看出它们的重要性不容忽视。

JavaScript 支持两种注释：单行注释 和 多行注释。

1. 单行注释

单行注释以双斜线开始，以行尾结束。

// 这是单行注释

推荐双斜线后插入一个空格，让注释文本有一定的偏移。

三种使用方式：

• 独占一行的注释，用以解释下一行代码。注释之前有一个空行，且缩进层级和下行代码一致
• 在代码行的尾部的注释。代码结束与注释之间至少有一个缩进，不应超过单行最大字符限制
• 批量注释掉多行代码

单行注释不应当以连续多行注释的形式出现，除非注释掉一大段代码。

// 好的写法
if (condition) {
  // 执行到这里，说明通过了所有安全性检查
  allowed();
}

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

// 不好的写法: 缩进不一致
if (condition) {
// 执行到这里，说明通过了所有安全性检查
  allowed();
}


// 好的写法
var result = num1 + num2;  // num2 不应当为 null

// 不好的写法: 代码和注释之间没有间隔
var result = num1 + num2;// num2 不应当为 null


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

// 不好的写法: 连续使用多个单行注释
// 这段代码非常难
// 我来解释一下
// 巴拉巴拉
if (condition) {
  allowed();
}

2. 多行注释

多行注释可以包裹跨行文本，以 /* 开始，以 */ 结束，如下

/* 注释 */

/* 第一行
第二行 */

/*
第一行
第二行
*/

以上注释都是合法的，但推荐使用 Java 风格的多行，如下

// 与文档注释是不同的，文档注释以 “/**” 打头。

/*
 * 第一行
 * 第二行
 */
var foo = 'bar';

多行注释之前应该有空行，之后紧跟代码，缩进层级与下行代码一致。

3. 使用注释

何时添加注释？一种通行的指导原则是：当代码不够清晰时添加注释，而当代码很明了时不应该添加注释。

如下，就是画蛇添足：

// 不好的写法

// 初始化 count
var count = 10;

上面的注释并没有提供其他有价值的信息。
如果这个值 10 具有特殊含义，而且无法直接从代码中看出来，这时就有必要添加注释了。

// 好的写法

// 改变这个值会让它变成青蛙
var count = 10;

如果没有注释，你不可能获得这些信息。
想象一下，如果你修改了 count 的值，会带来让你困惑不解的变化，一切都源于你没有写这句注释。

因此，添加注释的一般原则是，在需要让代码变得更清晰时添加注释。

3.1. 难于理解的代码

难以理解的代码通常都当添加注释。
根据代码的用途，你可以用单行注释、多行注释、文档注释。
关键是让其他人更容易读懂这段代码。

3.2. 可能被误认为错误的代码

另一个适合添加注释的好时机是当代码看上去有错误时。

在团队开发中，总是会有一些好心的开发中在编辑代码时发现他人的代码错误，就立刻将它修复。
有时这段代码并不是错误，所以“修复”这个错误往往会造成其他错误。

当你写的代码有可能会被别的开发者认为有错误时，则需要添加注释，如下：

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

这段代码中，在循环控制条件中使用了一个赋值运算符。
这不是标准用法，并常常被检测工具认为是有问题的。

如果你对这段代码不熟悉，且没有注释，很可能误认为这是一个错误，
猜想作者的本意是使用比较运算符(==)而不是赋值运算符(=)。

这行末尾的注释说明作者是有意为之的，即赋值而非比较。
这时，其他开发者读到这段代码时就不会将它“修复”。

3.3. 浏览器特性 hack

为了让低级浏览器正常工作，程序员常常会编写一些低效的、不雅的代码，这些代码可能会误认为是错误的代码。
这些 hack 代码可能隐含一些错误。

var ret = false;

if (/* ... */) {

} else if (/* ... */) {
  // 如果 needle 不是 ELEMENT_NODE 时，IE 和 Safari 下会有错误
  if (Y.UA.opera || needle[NODE_TYPE] === 1) {
    // ...
  }
} else if (/* ... */) {

}

4. 文档注释

文档注释并不是 JavaScript 的组成部分，但它们是一种普遍的实践。

最流行的文档注释的格式来自于 JavaDoc 文档格式，如下

/**
 * 如果需要深拷贝（deep copy），请使用 clone()
 * @method merge
 * @param {Object} 被合并的一个或多个对象
 * @return {Object} 一个新的合并后的对象
 */
Y.merge = function() {
  // ...
}

在开源项目中 JSDoc Toolkit 这个文档生成工具应用的非常广泛，支持 JavaDoc 风格的文档注释，支持在注释中使用 HTML 语法。