【读书笔记】：《编写可维护的JavaScript》第02章 注释

第02章 注释

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

2.1 单行注释

独占一行的注释，用来解释下一行代码。这行注释之前要有一个空行，且缩进层级和下一行的代码保持一致。
在代码行尾部的注释，代码结束到注释之间至少一个缩进。但该行的总长度不应该超过单行最大长度，如果超了，就将注释放到该行代码上方。
被注释掉的大段代码。这种情况不建议使用多行注释。

// 好的做法 注释前要有空行  注释要与被注释的代码相同缩进  
if(con){

    // 如果代码执行到这里，。。。
    allowed();
}

// 好的写法  注释写在代码后面时，要与代码之间有间隔
var result = something + somethingElse; // somethingElse不应当取值为null。

// 好的做法 注释掉大段代码 要使用单行注释 不建议使用多行注释
// if(con){
//  allowed();
// }

2.2 多行注释

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

/* 我是注释 */
/* 另一段注释 */

多行注释建议使用以下格式：

/*
 * 多行注释
 * 该注释包含两行
 */

2.3 使用注释

添加注释的一般原则：在需要让代码更清晰时添加注释
难于理解的代码
可能被误认为是错误的代码
浏览器特效hack

2.4 文档注释

如果想导出帮助文档API文件，那么就可以在方法或类的前面使用文档注释
文档注释有很多种格式，但最流行的一种格式来自于JavaDoc文档格式：多行注释以单斜线加双星号（/**）开始，
一般编辑器只要键入/**后enter回车就好