版权声明：署名，允许他人基于本文进行创作，且必须基于与原先许可协议相同的许可协议分发本文 （Creative Commons）
原文地址：https://liujiao111.github.io/2019/06/20/clean-code-doc/
好的注释有巨大的好处，而坏的注释却是大恶。注释是为了弥补代码表达意图的失败，因此，注释总是一种失败，所以要写注释之前，看看能否用代码来表达
因为代码最可信，代码会变动，而注释不总是跟着变，它会撒谎。
注释不能美化糟糕的代码
尽量将代码写得带有少量注释，而表达式更强、更整洁
用代码来阐述
尽量用代码来表达你的意图
例如：
//Chech to see if the employee is eligible for full benefits
if((employee.flags & HOURLY_FLAG) && (emplyee.age > 65)) {
}
去掉注释，用代码表达：
if((employee.isEligibleForFullBenefits()) {
}
看吧，不用注释，用代码是不是更清晰了。
好注释
当然，有些注释是必须的，是哪些呢？
- 法律信息
- 提供信息的注释，例如在抽象方法上注释说明该函数的作用以及返回值,当然，最好是可以通过名称命名就表达出意图而非注释
- 提供了对某个意图的解释
- 阐释：把那些晦涩难懂的表达翻译为易懂的表达式
- 警告：用于警告其他人对该代码块的操作
- TODO注释：定期查看，删除不必要的TODO
- 放大：可以用来某些不合理之物的重要性
- 公共API中的JAVADOC
坏注释
坏注释通常是糟糕的代码的借口，包括以下几类：
- 喃喃自语：
- 多余的注释：如果代码已经能解释清楚逻辑，再加上注释就是多此一举
- 误导性注释
- 循规式注释：不是每个方法都要有注释
- 日志式注释：千万不要把日志写到注释上
- 废话注释
- 能用函数或变量就不要写注释
- 位置标记，例如一堆斜杠
- 括号后面的注释
- 归属与署名：版本管理系统已经有详细记录了，不必写注释记录
- 注释掉的代码：没啥乱用，删除
- HTML注释
- 非本地信息：注释应该只描述当前代码的信息
- 信息过多
- 不明显的联系：注释及其描述的代码之间的联系应该显而易见
- 函数头：短函数不需要做太多事情，通过好的名字代码注释解释
总之，能用代码解释的，就不要写注释，如果一定要写，那就写的简短有力。
电子书免费共享：链接:
https://pan.baidu.com/s/1wvoRJGonA70J9hFn_w5jwA
提取码: 37jy