《编写可维护的JavaScript》——2.2 多行注释

本节书摘来自异步社区《编写可维护的JavaScript》一书中的第2章，第2.2节，作者： 【美】Nicholas C. Zakas 译者： 李晶 , 郭凯 , 张散集 更多章节内容可以访问云栖社区“异步社区”公众号查看。

2.2　多行注释

多行注释可以包裹跨行文本。它以/开始，以/结束。多行注释不仅仅可以用来包裹跨行文本，这取决于你。下面这些都是合法的注释。

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

尽管从技术的角度看，这些注释都是合法的，但我比较青睐Java风格的多行注释。Java风格的注释至少包含三行：第一行是/，第二行是以开始且和上一行的保持左对齐，最后一行是/。这种注释看起来像下面这样。

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

通过在注释块左侧注上星号，会让注释更加清晰。有一些IDE（比如NetBean和Eclipse）会为你自动插入这些星号。

多行注释总是会出现在将要描述的代码段之前，注释和代码之间没有空行间隔。和单行注释一样，多行注释之前应当有一个空行，且缩进层级和其描述的代码保持一致。来看下面这段例子。

// 好的写法
if (condition) {
     /*
      * 如果代码执行到这里
      * 说明通过了所有的安全性检测
      */
     allowed();
}
// 不好的写法：注释之前无空行
if (condition) {
     /*
      * 如果代码执行到这里
      * 说明通过了所有的安全性检测
      */
     allowed();
}
// 不好的写法：星号后没有空格
if (condition) {
     /*
      *如果代码执行到这里
      *说明通过了所有的安全性检测
      */
     allowed();
} 
// 不好的写法：错误的缩进
if (condition) {
/*
 * 如果代码执行到这里
 * 说明通过了所有的安全性检测
 */
     allowed();
}
// 不好的写法：代码尾部注释不要用多行注释格式
var result = something + somethingElse; /*somethingElse 不应当取值为null*/