什么是好的注释？

为什么要写注释？

什么也比不上防止良好的注释来的有用，什么也不会比乱七八糟的注释更有本事搞乱一个模块，什么也不会比陈旧、提供错误信息的注释更有破坏性。

所以良好的注释是提高代码质量重要的一环。

注释的恰当用法是弥补我们在用代码表达意图时遭遇的失败，如果发现自己需要写注释，就再想想看是否有办法用代码来表达。

注释存在时间越久，离其所描述的代码就越远，就越来越变得全然错误，原因是程序员没有坚持维护注释。

程序员应当负责将注释保持在可维护、有关联、精确的高度。

注意：注释不能梅花糟糕的代码，与其花时间编写解释你写出的糟糕代码的注释，不如花时间清理那堆糟糕的代码。

好注释

最好的注释是不写注释也能轻易的理解代码。

与法律有关的内容。例如版权及著作声明。

用注释来提供基本信息，如描述某个抽象方法的返回值。

对意图的注释。有时注释不仅提供了有关实现的有用信息，还反映了某个决定后面的意图。比如程序员在两个解决方案中选择了其中一个，其他阅读者或许不同意这个选择，但至少能知道他想干什么。

注释把某些晦涩难明的参数或返回值的意义，翻译为某种可读形式。

警示作用。用于警示其他程序员可能会出现某种后果的注释也是有用的。

注释可以用来放大某种看来不合理之物的重要性。

坏注释

喃喃自语型。如果只是因为你觉得应该或者因为过程需要就添加注释，那就要花必要的时间确保写出最好的注释，而不是谜团般的喃喃自语。

多余的注释。简单函数没必要写注释。通过函数名、变量名即可表达清楚意图。

日志式注释。如果在很久以前，在模块开始处创建并坚持维护这些记录还算有道理，否则只会令模块变得凌乱，应当删除。

位置标记。有的程序员喜欢在源代码中标记某个特别的位置，如一大串斜杠、一大串横线等，如果滥用标记，就会沉默在背景噪音中而被忽略。

注释掉的代码。直接把代码注释掉而不描述原因是最讨厌的做法。其他人不敢删除，他们会想，代码依然放在那，一定有其原因，而且这段代码很重要，不能删除。注释掉的代码堆积在一起，就像破酒瓶底的渣滓一般。

非本地信息。假如一定要写注释，请确保它描述了离它最近的代码。别在本地注释的上下文环境中给出了系统级的信息。

不明显的关系。注释及其描述的代码之间的联系应该显而易见，至少让读者能看到注释和代码、并且理解注释所谈何物。