《代码整洁之道》第 4 章 注释
第 4 章 注释
4.1 注释不能美化糟糕的代码
带有少量注释的整洁而有表达力的代码，要比带有大量注释的零碎而复杂的代码像样得多。与其花时间编写解释你搞出的糟糕的代码的注释，不如花时间清洁那堆糟糕的代码。
4.2 用代码来阐述
只要想上那么几秒钟，就能用代码解释你大部分的意图。很多时候，简单到只需要创建一个描述与注释所言同一事物的函数即可。
4.3 好注释
-
提供信息的注释
-
对意图的解释：注释不仅提供了有关实现的有用信息，而且还提供了某个决定后面的意图。你也许不同意程序员给这个问题提供的解决方案，但至少你知道
他想干什么。 -
阐释：有时，注释把某些晦涩难明的参数或返回值的意义翻译为某种可读形式，也会是有用的。通常，更好的方法是尽量让参数或返回值自身就足够清楚；但如果参数或返回值是某个标准库的一部分，或是你不能修改的代码，帮助阐释其含义的代码就会有用。
-
警示：有时，用于警告其他程序员会出现某种后果的注释也是有用的。例如，下面的注释解释了为什么要关闭某个特定的测试用例。
// Don't run un1ess you have some time to kill public void _testwithReallyBigFile() { ... } -
TODO 注释：
有时，有理由用//TODO形式在源代码中放置要做的工作列表。在下例中，TODO注释
解释了为什么该函数的实现部分无所作为，将来应该是怎样。//TODO-MdM these are not needed // We expect this to go away when we do the checkout model protected Vers ionInfo makeVersion() throws Exception { return null; }TODO 是一种程序员认为应该做，但由于某些原因目前还没做的工作。它可能是要提醒删除某个不必要的特性，或者要求他人注意某个问题。它可能是恳请别人取个好名字，或者提示对依赖于某个计划事件的修改。无论 TODO 的目的如何，它都不是在系统中留下糟糕的代码的借口。
-
放大：注释可以用来放大某种看来不合理之物的重要性。
-
公共 API 中的 Javadoc：如果你在编写公共 API，就该为它编写良好的 Javadoc。
4.4 坏注释
- 循规式注释：所谓每个函数都要有 Javadoc 或每个变量都要有注释的规矩全然是愚蠢可笑的。这类注释徒然让代码变得散乱，满口胡言，令人迷惑不解。
- 日志式注释：很久以前，在模块开始处创建并维护这些记录还算有道理。那时，我们还没有源代码控制系统可用。如今，这种冗长的记录只会让模块变得凌乱不堪，应当全部删除。
- 注释掉的代码：其他人不敢删除注释掉的代码。他们会想，代码依然放在那儿，一定有其原因，而且这段代码很重要，不能删除。注释掉的代码堆积在一起，就像破酒瓶底的渣滓一般。
