2.1 单行注释
单行注释以两个斜线开始,以行尾结束。
单行注释有三种写法:
(1)独占一行的注释,用来解释下一行代码。这行注释之前总是有一个空行,且缩进层级和下一行保持一致。
(2)在代码行的尾部的注释。代码结束到注释之间至少有一个缩进。注释(包括之前的代码部分)不应当超过单行最大字符数限制,如果超过了,就将这条注释放置于当前代码行的上方。
(3)被注释掉的大段代码(很多编辑器都可以批量注释掉多行代码)。
单行注释不应当以连续多行注释的形式出现,除非你注释掉一大段代码。只有当需要注释一段很长的文本时才使用多行的注释。
// 好的写法 if (condition) { // 如果代码执行到这里,则表明通过了所有安全性检查 doSomething(); } // 不好的写法:注释之前没有空行 if (condition) { // 如果代码执行到这里,则表明通过了所有安全性检查 doSomething(); } // 不好的写法:错误的缩进 if (condition) { // 如果代码执行到这里,则表明通过了所有安全性检查 doSomething(); } // 好的写法 var result = something + somethingElse; //somethingElse不应当取值为null // 不好的写法:代码和注释之间没有间隔 var result = something + somethingElse;//somethingElse不应当取值为null // 好的写法 // if (condition) { // doSomething(); // } // 不好的写法:这里应当用多行注释 // 接下来的这段代码非常难,那么,我来详细解释一下 // 这段代码的作用是首先判断条件是否为真 // 只有当为真时才会执行 // 多个函数计算出来的,在整个会话生命周期内 // 这个值是可以修改的 if (condition) { // 如果代码执行到这里,则表明通过了所有安全性检查 doSomething(); }
2.2 多行注释
多行注释可以包裹跨行文本。它以/*开始,以*/结束。
Java风格的注释至少包含三行:第一行是/*,第二行是以*开始且和上一行的*保持左对齐,最后一行是*/。
多行注释总是会出现在将要描述的代码段之前,注释和代码之间没有空行间隔。和单行注释一样,多行注释之前应当有一个空行,且缩进层级和其描述的代码保持一致。
// 好的写法 if (condition) { /* * 如果这行代码执行到这里 * 说明通过了所有安全性检测 */ doSomething(); } // 不好的写法:注释之前没有空行 if (condition) { /* * 如果这行代码执行到这里 * 说明通过了所有安全性检测 */ doSomething(); } // 不好的写法:星号后面没有空格 if (condition) { /* *如果这行代码执行到这里 *说明通过了所有安全性检测 */ doSomething(); } // 不好的写法:错误的缩进 if (condition) { /* *如果这行代码执行到这里 *说明通过了所有安全性检测 */ doSomething(); } // 不好的写法:代码尾部注释不要用多行注释风格 var result = something + somethingElse; /*somethingElse不应当取值为null*/
2.3 使用注释
一种通行的指导原则是,当代码不够清晰时添加注释,而当代码很明了时不应当添加注释。比如下面的例子,注释是画蛇添足。
// 初始化count
var count = 10;
因为代码中初始化count的操作是显而易见的。注释并没有提供其他有价值的信息。换个角度讲,如果这个值10具有一些特殊的含义,而且无法直接从代码中看出来,就没有必要添加注释了。
// 改变这个值可能会让它变成青蛙
var count = 10;
如果没有添加注释,你修改了count的值,变成了青蛙,就会让人困惑不解。
因此,添加注释的一个原则是,在需要让代码变得更清晰时添加注释。
2.3.1 难于理解的代码
难于理解的代码通常都应当加注释。根据代码的用途,你可以进行单行注释,多行注释,或者混合使用这两种注释。关键是让其他人更容易读懂这段代码。
2.3.2 可能被误认为错误的代码
另一个适合添加注释的好时机是当代码看上去有错误时。在团队开发中,总是会有好心的开发者在编辑代码时发现他人的错误代码,就立即将它修复。有时这段代码并不是错误的源头,所以“修复”这个错误往往会制造其他错误,因为本次修改应当是可追踪的。当你写的代码有可能会被别的开发者认为有错误时,则需要添加注释。
2.3.3 浏览器特性hack
JavaScript程序员常常会编写一些低效的、不雅的、彻头彻尾的肮脏代码,用来让低级浏览器正常工作。实际上这种情形是一种特殊的“可能被误认为是错误的代码”:这种不明显的做浏览器特性Hack的代码可能隐含一些错误。
2.4 文档注释
JavaDoc文档格式:多行注释以单斜线加双星号(/**)开始,接下来是描述信息,其中使用@符号来表示一个或多个属性。
/** * 这是一个计算整数和的方法 * @method addNumber * @param {Number} 整数 * @return {Number} 一个计算后的结果 */ var addNumber = function (x, y) { return x + y; }
当使用文档注释时,你应当确保对如下内容添加注释。
(1)所有的方法
应当对方法、期望的参数和可能的返回值添加注释描述。
(2)所有的构造函数
应当对自定义类型和期望的参数添加注释描述。
(3)所有包含文档化方法的对象
如果一个对象包含一个或多个附带文档注释的方法,那么这个对象也应当适当地针对文档生成工具添加文档注释。
当然,注释的格式和用法最终还是由你所选择的文档生成工具决定的。