《编写可维护的JavaScript》——第 2 章　注释2.1　单行注释

第 2 章　注释

注释是代码中最常见的组成部分。它们是另一种形式的文档，也是程序员最后才舍得花时间去写的。但是，对于代码的总体可维护性而言，注释是非常重要的一环。打开一个没有任何注释的文件就好像趣味冒险，但如果给你的时间有限，这项任务就变成了折磨。适度的添加注释可以解释说明代码的来龙去脉，其他开发者就可以不用从头开始读代码，而是直接去读代码的任意部分。编程风格通常不会包含对注释的风格约定，但我认为从注释的作用即可看出它们的重要性不容忽视。

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

2.1　单行注释

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

// 这是一句单行注释

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

独占一行的注释，用来解释下一行代码。这行注释之前总是有一个空行，且缩进层级和下一行代码保持一致。
在代码行的尾部的注释。代码结束到注释之间至少有一个缩进。注释（包括之前的代码部分）不应当超过单行最大字符数限制，如果超过了，就将这条注释放置于当前代码行的上方。
被注释掉的大段代码（很多编辑器都可以批量注释掉多行代码）。
单行注释不应当以连续多行注释的形式出现，除非你注释掉一大段代码。只有当需要注释一段很长的文本时才使用多行注释。

这里有一些示例代码。

// 好的写法
if (condition) {
     // 如果代码执行到这里，则表明通过了所有安全性检查
     allowed();
}
// 不好的写法：注释之前没有空行
if (condition) {
     // 如果代码执行到这里，则表明通过了所有安全性检查
     allowed();
}
// 不好的写法：错误的缩进
if (condition) {
// 如果代码执行到这里，则表明通过了所有安全性检查
     allowed();
}
// 好的写法
var result = something + somethingElse; // somethingElse不应当取值为null
// 不好的写法：代码和注释之间没有间隔
var result = something + somethingElse;// somethingElse不应当取值为null
// 好的写法
// if (condition) {
//       doSomething();
//       thenDoSomethingElse();
// }
// 不好的写法：这里应当用多行注释
// 接下来的这段代码非常难，那么，让我详细解释一下
// 这段代码的作用是首先判断条件是否为真
// 只有为真时才会执行。这里的条件是通过
// 多个函数计算出来的，在整个会话生命周期内
// 这个值是可以被修改的
if (condition) {
     // 如果代码执行到这里，则表明通过了所有安全性检查
     allowed();
}