第一部分 编程风格

第2章 注释

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

2.1 单行注释

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

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

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

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

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

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

2.2 多行注释

多行注释可以包裹跨行文本，它以/*开始，以*/结束。 和单行注释一样，多行注释之前应当有一空行，且缩进层级和其描述的代码保持一致。

2.3 使用注释

何时添加注释是程序员经常争论的一个话题。一种通行的指导原则是，当代码不够清晰时添加注释，而当代码很明了时不应当添加注释。

2.3.1 难于理解的代码

难于理解的代码通常都应当加注释。

2.3.2 可能被误认为错误的代码

当代码看上去有错误时，需要添加注释。

2.3.3 浏览器特性hack

我们常常需要编写一些低效的、不雅的、彻头彻尾的肮脏代码，用来让低级浏览器正常工作。避免让别人误改动，应该添加注释。

2.4 文档注释

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