注释-《代码整洁之道》读书笔记(三)

原文地址：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