对注释的态度

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

程序员应当复杂将注释保持咋可维护、有关联、精确的高度。我同意这种说法，但我更主张把力气用在写清楚代码上，直接保证无须编写注释。

只是只在移除地方有：代码。只有代码能忠实地告诉你它做的事。那是唯一真正准确的信息来源。所以，尽管有时也需要注释，我们也应该花心思尽量减少注释量。

注释不能美化糟糕的代码

与其花时间编写糟糕代码的注释，不如花时间清洁那堆糟糕的代码。

用代码来阐述

很多时间，简单到只需要创建一个描述与注释所表达的同一意思的函数即可。

用更好的函数名代替注释

好注释

唯一真正好的注释是你想办法不去写的注释。

法律信息

每隔源文件开头放置的标准注释

这类注释不应是合同或法典，如有可能，就指向一份标准许可或外部文件。

提供信息的注释

有时，利用注释来提供基本信息，例如解释在某个抽象方法中返回值

但是把函数重新命名为responderBeingTested, 注释就是多余的了。

对意图的解释

注释不仅提供有关实现的有用信息，而且还可以提供某个决定后面的意图。即在注释中告诉别人你的想法。

阐释

用注释把某些晦涩难懂的参数或返回值的意义翻译为某种可读形式，会是有用的。不过，通常更好的方法是尽量让参数或返回值自身就足够清除。

当然要注意的是，要确认注释的正确性。

警示

用于警告其他程序员会出现某种后果的注释。

TODO注释

TODO是一种程序员认为应该做，但由于某些原因还没做的工作。他可能是要提醒删除某个不必要的特性，或者要求他人注意某个问题。

IDE都提供了TODO注释的定位及高亮功能，定期查看，删除不在需要的注释。

放大

用注释强调某件事的重要性

公共API中的文档注释

如果在编写公共API，就应该编写良好的文档

坏注释

大多数注释都属于此类，通常坏注释都是糟糕代码的支撑或接口，或者对错误决策的修正。基本上等于程序员自说自话。

喃喃自语

如果只是因为你觉得应该或者因为过程需要添加注释，那就是无谓之举。如果你决定写注释，就必须花时间写好注释。

多余的注释

这种注释并不能比代码本身提供更多信息，它没能证明代码的意义，也没能给出代码的意图或逻辑。

多余的注释：

误导性注释

避免描述不够准确、歧义、误导性的注释，如果连你自己都没搞懂注释的意义，为什么期待别人能懂呢？

循规式注释

每隔函数都要有说明或者每个变量都要有注释。这类注释徒然让代码变得散乱，满口胡言，令人迷糊不解。

日志式注释

废话注释

用整理代码的决心替代创造废话的冲动吧。你会发现自己成为更优秀、更快乐的程序员。

可怕的废话

能用函数或者变量就别用注释

括号后的注释

尽管这对于含有深度嵌套结构函数可能有意义，但只会给我们更愿意编写短小、封装的函数带来混乱。如果你发现自己想标记右括号，其实应该做的事缩短函数。

注释掉的代码

别这么干，直接注释代码，会让你的同事怀疑这代码到底有什么用，造成混乱。

非本地信息

假如你一定要写注释，请确保描述了离它最近的代码。

信息过多

别在注释中添加历史性话题、或者无关的细节描述。

不明显的联系

注释及其描述代码之间的联系应该显而易见。

范例

作者的另一本书《敏捷软件开发：原则、模式与实践》