本节书摘来自异步社区《编写可维护的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*/