编写可维护的JavaScript----笔记(二)
01.何时使用注释
添加注释的一般原则是,在需要让代码变得更清晰时添加注释
- 难于理解的代码
- 浏览器特性hack
- 注释声明:
- TODO 说明代码还没完成,应当包含下一步要做的事情
- XXX 说明代码是有问题的应当尽快修复
- FIXME 说明代码是有问题的,应尽快修复,重要性仅次于XXX
- REVIEW说明代码在任何可能的改动都需要评审
02.单行注释
单行注释有三种使用方式
-
独占一行的注释,用来解释下一行代码。这行注释之前总有一个空行切缩进层级和下一行代码保持一致
-
在代码行的尾部的注释,用来解释他之前的代码。代码结束到注释之间至少有一个缩进,并且不能超过单行最大字符数限制
-
多行,用来注释一个代码块
03.多行注释
每个多行注释都至少有如下三行:
-
首行仅仅包括/*注释开始,该行不应该有其他文字,并且应当保持同他描述代码的相同层次的缩进
-
接下来的行以*开头并保持左对齐。这些行可以有文字描述,且应当有同样层次的缩进并附加一个空格
-
最后一行以*/开头并同先前行保持对齐,也不应该有其他文字
-
每个多行注释前应当预留一个空行