“别给糟糕的代码加注释——重新写吧”
Brian W.Kernighan与P.J.Plaugher
1. 注释不能美化糟糕的代码
2. 用代码来阐述
3. 好注释
- 法律信息
- 提供信息的注释 如：解释正则表达式的作用
- 对意图的解释
- 阐释 对于某些不能修改的代码，阐释其含义
- 警示
- TODO注释 TODO是程序员认为应该做，但由于某些原因目前还没做的工作
- 放大 放大某种看来不合理之物的重要性
4. 坏注释
- 喃喃自语 仅只是因为觉得应该或者因为过程需要就添加注释
- 多余的注释
- 误导性的注释 注释往往不够精确
- 循规式注释
- 日志式注释
- 废话式注释
- 能用函数或变量时就别用注释
- 位置标记 不要滥用标记栏
- 括号后面的注释 如：标记循环结束的括号 //while
- 归属或署名 源代码控制系统是这类信息最好的归属地
- 注释掉的代码
- HTML注释
- 非本地信息
- 信息过多
- 不明显的联系 注释及其描述的代码之间的联系应该显而易见
- 函数头注释