CleanCode笔记---注释

CleanCode

更多内容详见:CleanCode笔记

什么也比不上放置良好的注释来的有用,什么也不会比乱七八糟的注释更有本事搞乱一个模块!

如果我们擅长用开发语言来表达意图,就不那么需要注释,甚至根本不需要!

注释的巧当用法是弥补我们在代码表达意图时遭遇失败.

如果你发现自己需要写注释,在想想看是否有办法不写注释.

程序员应当负责将注释保持在可维护,有关联,精确的高度.

注释不能美化代码

写注释的常见动机之一是糟糕代码的存在.与其花时间编写注释不如花时间清洁糟糕的代码.

用代码来阐述

比如以下代码:

//check to see if the employee is eligible for full benfits
if((employee.flag & HOURLY_FLAG) && (employee.age > 65))

为何不改为:

if(employee.isEligibleForFullBenefits())

只需要几秒钟,就能用代码解释大部分的意图.

好注释

好注释有以下几项:
1. 法律信息
2. 提供信息的注释
3. 对意图的解释
4. 阐释
5. 警示
6. TODO注释
7. 放大
8. 公共API中的javadoc

坏注释

坏注释包括以下:
1. 呐呐自语
2. 多余的注释
3. 误导性注释
4. 循规式注释
5. 日志式注释
6. 位置标记
7. 括号后的注释
8. 归属与署名
9. 注释掉的代码
10. HTML注释
11. 非本地信息
12. 信息过多
13. 不明显的联系
14. 函数头
15. 非公共代码中的javadoc

切记能用函数或变量就别用注释