可读性：★★★★✰ 理解难度：★★★✰✰
概述
注释并不像《辛德勒名单》。它们并不“纯粹的好”。实际上，注释最多也就是一种必需的恶。
作者并不推荐写不必要的注释，只有在不得不的情况下才需要注释。
1.注释不能美化糟糕的代码
“别给糟糕的代码加注释，重新写吧。”
使用注释的优先级：用代码来阐述（没有注释） > 使用注释 > 坏的注释。
2.好注释
有的注释是必需的，也是有利的。
1) 对意图的解释
描述你写这段代码的目的。
有时，当你看到这类注释，也许不同意程序员给这个问题提供的解决方案，但至少你知道他想干什么。
2) 阐释
有时，把一些晦涩难懂的参数或者返回值翻译为通俗易懂的形式，也是有用的。
比如underscore.js库的一些方法说明：
underscore.rest(useList) // 返回数组中除第一个元素外的其他元素。
underscore.flatten(useList) // 把嵌套多层的数组转化成一层，[1,2,[3]] => [1,2,3]
3) 警示
对于一些方法调用的缺陷的说明，或者提醒关闭某个被开启的线程。
// 注意：这个方法可能会消耗一些性能
traverse(list) {}
4) TODO注释
有时，由于时间或者环境关系，一些需要后期完善的部分，可以通过todo注释标注出来。但是一定要记得定期解决掉这些备注的todo事项。不过还是尽量不要使用，因为Later equals never
5) 强调
有时，需要强调一下某段逻辑看似不合理，但是为何还是这么做了，说明其不合理的重要性。以防止读者无法理解，或者被轻易改掉。
3.坏注释
哪些注释会显得特别没有必要。
1) 自言自语
try {
doSmthing()
} catch() {
// 现在还不太清楚这个异常怎么处理，后面想好再说吧。
}
2) 多余的注释
有时，读多余的注释的时间没准比读代码的时间还要长。
// 这是一个对用户列表的遍历，目的是为了找出名字长度多于2个字的用户，并且把他们放入集合a
let a = []
for (let i=0; i<userList.length; i++) {
if (userList[i].name.length > 2) {
a.push(userList[i])
}
}
3) 误导型注释
有时，比起不写注释更具杀伤性的行为是写误导性注释。不仅不能有所帮助，甚至会引起不必要的麻烦。
所以一定要保证注释的准确性。
4) 死板型注释
方法本身的意思已经一目了然，没有必要增加一些多余的模板。
/*
* @param title CD的名称
* @param author CD的创作者
* @param publishDate CD的发行时间
* @param time CD的时长
*/
function addCD(title, author, publishDate, time)
5) 日志型注释
有时，有的同学会写一些修改的日志作为注释，类似谁修改过代码，什么时间点修改的。
这些日志型的注释我们现代的代码编辑器都记录的很清楚，没有必要画蛇添足。
6) 标记型注释
有时，为了方便查找，有的同学会使用一些标记型注释，这种注释临时使用后，记得删除，否则多了之后，代码会显示凌乱丑陋。
// 这里 ///////////////////////
doSmthing() {}
7) 注释掉的代码
有时，有的同学会把不用的代码注释掉。其他人又不敢删除，他们会想，依然放在那儿，一定有其用途。这种方式同样会使得程序丑陋不堪。
如果是担心代码无法恢复，大可不必，现代编辑器对于修改的记录都十分完善。
doSmthing()
// for (let i=0; i<users.length; i++) {
// if (a) {
// doAction()
// }
// }
doSmthingElse()
本文参考《代码整洁之道》（Robert C. Martin著，韩磊译）。
浙江大华技术股份有限公司-软研-智慧城市产品研发部招聘高级前端，欢迎来撩，有意向可发送简历到chen_zhen@dahuatech.com，长期有效
上一篇：三、函数
下一篇：五、格式
