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

注释不能美化糟糕的代码

带有少量注释的简洁而有表达力的代码，要比带有大量注释的零碎而复杂的代码像样的多。与其花时间编写解释你搞出来的糟糕的代码的注释，不如花时间清洁那堆糟糕的代码。

用代码来阐述

好注释

法律信息。如版权及著作权声明。

提供信息的注释。更好的方式是尽量利用函数名称传达信息。

警示信息。

TODO 注释。

公共 API 中的 Javadoc。

坏注释

喃喃自语。

多余的注释。相对于代码，并没有提供更多的信息。

误导性注释。

循规式注释。不是每个函数、每个变量都要有注释。

日志式注释。在有了版本控制系统的情况下，这种注释就是废话。

废话注释。

能用函数或变量时就不要用注释。

归属与署名是不必要的。版本控制系统全部记着呢。

注释掉的代码。千万不要这么干！

HTML 注释。不要这么写。不够易读。

信息过多。不要说多余的东西。

为只做一件事的短函数选个好名字，通常比函数头写注释要好。