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

我为什么要极力贬低注释？因为注释会撒谎。也不是说总是如此或有意如此，但出现得实在太频繁。注释存在的时间越久，就离其所描述的代码越远，越来越变得全然错误。原因很简单。程序员不能坚持维护注释。

代码在变动，在演化。从这里移到那里。彼此分离、重造又合到一处。很不幸，注释并不总是随之变动——不能总是跟着走。注释常常会与其所描述的代码分隔开来，孑然飘零，越来越不准确。

不准确的注释要比没注释坏得多。它们满口胡言。它们预期的东西永不能实现。它们设定了无需也不应再遵循的旧规则。

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

注释不能美化糟糕的代码

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

用代码来阐述

// 检查员工是否有资格享受全额福利
if ((employee.flags & HOURLY_FLAG) &&(employee.age > 65))

还是这个？
if (employee.isEligibleForFullBenefits())

只要想上那么几秒钟，就能用代码解释你大部分的意图。很多时候，简单到只需要创建一个描述与注释所言同一事物的函数即可。

TODO注释

TODO是一种程序员认为应该做，但由于某些原因目前还没做的工作。它可能是要提醒删除某个不必要的特性，或者要求他人注意某个问题。它可能是恳请别人取个好名字，或者提示对依赖于某个计划事件的修改。无论TODO的目的如何，它都不是在系统中留下糟糕的代码的借口。

多余的注释

    /*
     * @param title The title of the CD
     * @param author The author of the CD
     * @param tracks The number of tracks on the CD
     * @param durationInMinutes The duration of the CD in minutes
     */
    public void addCD(String title, String author, int tracks, int durationInMinutes) {
        CD cd = new CD();
        cd.title = title;
        cd.author = author;
        cd.tracks = tracks;
        cd.duration = duration;
        cdList.add(cd);
    }

所谓每个函数都要有 Javadoc 或每个变量都要有注释的规矩全然是愚蠢可笑的。这类注释徒然让代码变得散乱，满口胡言，令人迷惑不解。

日志式注释

有人会在每次编辑代码时，在模块开始处添加一条注释。这类注释就像是一种记录每次修改的日志。我见过满篇尽是这类日志的代码模块。

* Changes (from 11-Oct-2001)
* --------------------------
* 11-Oct-2001 : Re-organised　the class and moved it to new package
*　　　　　　　　　　　com.jrefinery.date (DG);
* 05-Nov-2001 : Added a getDescription() method, and　eliminated NotableDate
*　　　　　　　　　　　class (DG);
* 12-Nov-2001 : IBD　requires　setDescription() method,　now that NotableDate
*　　　　　　　　　　　class is gone (DG);　Changed getPreviousDayOfWeek(),
*　　　　　　　　　　　getFollowingDayOfWeek() and getNearestDayOfWeek()　to correct
*　　　　　　　　　　　bugs (DG);
* 05-Dec-2001 : Fixed bug in　SpreadsheetDate　class (DG);

很久以前，在模块开始处创建并维护这些记录还算有道理。那时，我们还没有源代码控制系统可用。如今，这种冗长的记录只会让模块变得凌乱不堪，应当全部删除。直接查看版本记录变更说明即可。

注释掉的代码

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

20世纪60年代，曾经有那么一段时间，注释掉的代码可能有用。但我们已经拥有优良的源代码控制系统如此之久，这些系统可以为我们记住不要的代码。我们无需再用注释来标记，删掉即可，它们丢不了。我担保。