代码坏味道与重构之注释

1. 注释的目的

编码最佳的实践是代码自注释，不写额外注释。但是有些场景我们不得不用注释，来帮助他人或者自己更好地理解代码，提升代码的可毒性和可维护性。

• 告诉别人如何使用自己的接口
• 辅助他人更好地理解自己写的代码
• 记录自己当初这么写的背景，避免别人误删

总之：注释的目的是帮助他人或者自己更好地理解、使用、维护代码。

2. 什么时候写注释

1. 对外提供给他人使用的接口、方法、类，一般都需要写注释，注明接口的功能、使用方式、注意事项等。比如 Java Doc 文档。
2. 复杂的算法或者特殊业务处理逻辑，需要加上注释，交代算法的思想或业务处理背景，降低代码的阅读成本，提升代码可读性和可维护性。
3. 紧急修复问题时，加的一些特殊处理和判断，需要加上注释，交代这么写的背景原因，避免误删。这很常见，我也干过，但是这种场景，通常会导致架构腐化，代码变得不整洁，应该记录技术债务，后面通过重构消除特殊处理和判断，提升代码的可读性和可维护性。

注释也是有很高的维护成本的，坏的注释比没有注释更可怕。

写注释也是一门学门，当你不知道该不该写注释时，除了用上面的场景判断，还有一个有效的方法就是代码 review。

如果检视你代码的几个人都能一眼看懂你的代码，那么你的注释就是多余的。如果大家都看不懂你的代码，一方面可能是你的代码写的不好，另一方面也可能是提醒你需要加注释了。

3. 糟糕注释及影响

开发中，我们可能会遇到以下糟糕的注释：

• 莫名其妙、晦涩难懂的注释。这种误导性最大，极大增加了代码的理解成本。
• 注释和代码实现不一致。这种伤害最大，代码可读性差，提升了代码的理解成本、维护成本，增加了代码犯错概率。
• 冗余的注释。代码已经很好自注释时，还加注释，增加了大脑的负担，降低了代码可读性和可维护性。
• 缺乏注释。核心算法或者业务逻辑没有注释，会导致接手的人花更多的时间理解代码。

4. 糟糕注释的重构技巧

注释本身其实没有重构一说，这里的重构目的是：

• 消除冗余的注释，达到代码自注释
• 更新注释，保证注释和代码实现一致
• 注释更好的帮助理解代码，提升代码可读性和可维护性

消除冗余注释，达到代码自注释有以下技巧：

1. 提取有意义的变量。Ctrl + Alt +V，如将一些判断，提取为有意义的局部变量，增加代码可读性，删除多余的注释。
2. 提取有意义的方法。Ctrl + Alt + M，如将一些复杂判断，提取为有意义的私有方法，增加代码可读性，删除多余的注释。
3. 方法、变量、类重命名。Shift + F6，取一个有意义的命名，来消除冗余的注释。

最后，注释是代码无法自注释的无奈之举，它必须为提升代码可读性和可维护性存在，否则注释不应该存在。