《编写可维护的JavaScript》读书笔记之编程风格-注释

注释

注释是代码中最常见的组成部分。它们是另一种形式的文档，也是程序员最后才舍得花时间去写的。但是，对于代码的总体可维护性而言，注释是非常重要的一环。适度的添加注释可以解释说明代码的来龙去脉，其他开发者就可以不用从头开始读代码，而是直接去读代码的任意部分。

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

单行注释

两个斜线开始，至行尾结束。

// 这是一句单行注释

【风格】：很多人喜欢在双斜线之后敲入一个空格（我也喜欢），用来让注释文本有一定的偏移。

【使用方法】：

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

【注意】：单行注释不应该以连续多行注释的形式出现，除非你注释掉一大段代码。

【示例】：

// 好的写法
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();
}

多行注释

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

【示例】：多行注释不仅仅可以用来包裹跨行文本，这取决于你。

/* 我的注释 */
/* 另一段注释
这段注释包含两行 */
/*
又是一段注释
这段注释同样包含两行
*/

【风格】：java 风格的多行注释。

/*
 * 另一段注释
 * 这段注释包含两行文本
 */

【说明】：至少包含三行，第一行为 /*，第二行开始以 * 开始且和上一行的 * 保持左对齐，最后一行为 */ 并且星号与之后的注释说明文字间隔一个空格。

【使用方法】：
总是出现在将要描述的代码段之前，注释和代码之间没有空行间隔。和单行注释一样，在多行注释之前应当有一个空行，且缩进层级和其描述的代码保持一致。

【示例】：

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

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

// 不好的写法：星号后没有空格
if (condition) {

    /*
     *如果代码执行到这里
     *说明通过了所有的安全性检查
     */
    allowed();
}

// 不好的写法：错误的缩进
if (condition) {

/*
 * 如果代码执行到这里
 * 说明通过了所有的安全性检查
 */
    allowed();
}

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

使用注释

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

【一般原则】：在需要让代码变得更清晰时添加注释。

难于理解的代码

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

可能被误认为错误的代码

当代码看上去有错误时，需要写上注释以防其他开发者好心进行“修复”。

浏览器特性 hack

JavaScript 程序员常常会编写一些低效的、不雅的、彻头彻尾的肮脏代码，用来让低级浏览器正常工作。实际上这种情形是一种特殊的“可能被误认为错误的代码”：这种不明显的做浏览器特性 Hack 的代码可能隐含一些错误。

文档注释

从技术角度来讲，文档注释并不是JavaScript的组成部分，但它们是一种普遍的实践。

【风格】：JavaDoc 文档格式。

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

【示例】：

/**
 ........
 @method merge
 @param {Object} 被合并的一个或多个对象
 @return {Object} 一个新的合并后的对象
 **/

【注意】：注释的详细格式和用法最终还是由你所选择的文档生成工具决定的。

【需要添加注释的内容】：

• 所有的方法：应当对方法、期望的参数和可能的返回值添加注释描述。
• 所有的构造函数：应当对自定义类型和期望的参数添加注释描述。
• 所有包含文档化方法的对象：如果一个对象包含一个或多个附带文档注释的方法，那么这个对象也应当适当地针对文档生成工具添加文档注释。