代码到底要不要注释 —— 读《Clean Code》Comment一章

Posted on 2019-08-25 Edited on 2019-09-01

代码注释问题是最容易被讨论的。我们常常听到这种说法，一份好的代码有一份完备的注释。又有一种说法，好的代码是自注释的。
说前者的，往往忽视了代码维护的难度。或者干脆就是外行，因为外行怎么能简单粗暴的评价一份代码的好坏呢？最简单的方法就是，注释多就是好代码，没注释就是烂代码。
说后者的往往是经过一些专业的训练，并有一些对维护代码自身的认识的。不过很多情况下，自注释是理想状态。注释有时是难免的。
我认为，通常情况下，当你想注释一段代码的时候，往往应该考虑怎么重构它，而让它更加semantic，如果实在做不到，或者重构的effort非常大，那么可以加一段注释，或者放一个TODO。但起码注释是一种提醒，你的代码或多或少有一点点坏味道了。

Good comments

有一些情况的comment避免不了，本书称之为good comment，暂且罗列，具体也可以参考Uncle Bob的书

Legal Comments
Informative Comments：注释里放一些逻辑抽象信息，而不要简单机械的重复具体的实现代码
Explanation of Intent
Clariﬁcation
Warning of Consequences
TODO Comments
Ampliﬁcation
Javadocs in Public APIs

即便是这些所谓的good comment，在添加的时候，也不应当是心安理得的。看作者的告诫：

If you are writing a public API, then you should certainly write good javadocs for it. But keep in mind the rest of the advice in this chapter. Javadocs can be just as misleading, nonlocal, and dishonest as any other kind of comment.

即便我们认为的绝对正义的java doc，作者也在警醒我们，这些注释仍然会年久失修，或者传递错误信息。
诚然！这也是我的经验。

Bad comments

在我的经验里，仍然有很多人仍然抱着注释即正义的思路。所以还是想着重指出什么样的注释是不应该的，实际上要么是无用的重复，要么是偷懒的表现。Clean Code一书给出的18个例子可以成为一份checklist来检验我们的代码。本文选取我经常遇到的几种

Mumbling

这种comment指的是，有时候，代码作者在写代码的时候，想要解释或者记录一些信息，便于后续查阅。但这时候通常都是以当时开发时的心境，写下的注释，往往缺乏很多隐含信息的描述。而这样的信息，在经过一段时间后，并不能提供很多有用的信息，而且如果当初的代码逻辑稍作变更，而注释没跟上的话，往往就会造成很多困扰。
例如文中的这个例子：

public void loadProperties() {
    try {
        String propertiesPath = propertiesLocation + "/" + PROPERTIES_FILE;       
        FileInputStream propertiesStream = new FileInputStream(propertiesPath);       
        loadedProperties.load(propertiesStream);
    } catch(IOException e) {
        // No properties files means all defaults are loaded
    }
}

这样的例子在我们的代码中非常常见，我猜这也是作者把这种类型的comment放到第一个的原因吧。在写代码时，我们往往都会有这样的冲动，而且往往这时候我们都自我感觉良好——看，我在做注释了，以后的人（有可能就是几天或者几周后的我）肯定会感激我。
Uncle Bob针对这段注释，发出了灵魂拷问：

Apparently, if we get an IOException, it means that there was no properties ﬁle; and in that case all the defaults are loaded.

But who loads all the defaults?

Were they loaded before the call to loadProperties.load?

Or did loadProperties.load catch the exception, load the defaults, and then pass the exception on for us to ignore?

Or did loadProperties.load load all the defaults before attempting to load the ﬁle?

Was the author trying to comfort himself about the fact that he was leaving the catch block empty? Or—and this is the scary possibility was the author trying to tell himself to come back here later and write the code that would load the defaults?

我认为这样的注释可以出现在最开始的版本里，像作者说的

你可能只是希望后面重新revisit做一些重构
或者可能只是不是想catch-block空着

不管是任何理由，都应该在注释里写清楚，如果希望revisit就写上TODO或者FIXME，如果暂时没考虑清楚要不要catch-block，那也写上TODO或者FIXME，并记录一个item，然后做完手上的一个case之后，回头过来把这里重构了，然后删掉这段注释。

Redundant Comments

这种注释也非常常见。例如：

// Utility method that returns when this.closed is true. Throws an exception 
// if the timeout is reached.
public synchronized void waitForClose(final long timeoutMillis) throws Exception {
    if(!closed)
    {
        wait(timeoutMillis);
        if(!closed) 
            throw new Exception("MockResponseSender could not be closed");
    }
}

再例如：

void read_from_file(const char *name)
{
    char buf[10] = {0};
    
    // open a file
    int fd = open(name, 'r');
    
    // read from it
    int nr = read(fd, buf, sizeof(buf));
    
    return atoi(buf);

这里的注释没有添加任何的附加信息，但是却增加了维护成本，因为代码改，注释就得改，否则就是misleading。我认为绝大多数程序员写这样注释的冲动，只是因为这样的注释让你自我感觉良好，因为我在写注释。

Misleading Comments

这往往出现在一段复杂的逻辑，开发者希望通过注释阐述逻辑的意义，但如果叙述不当，容易产生误解，再如果逻辑有了些许变更，而注释没跟上。那么这个注释就会变成一个大坑，让原本就难以理解的代码更加晦涩难懂。
例如这一段：

// Utility method that returns when this.closed is true. Throws an exception 
// if the timeout is reached.
public synchronized void waitForClose(final long timeoutMillis) throws Exception {
    if(!closed)
    {
        wait(timeoutMillis);
        if(!closed) 
            throw new Exception("MockResponseSender could not be closed");
    }
}

第二个if(!closed),没有出现在注释里，是后加的，还是一开始就没描述清楚？到底是注释对还是代码对？
这种情况，应该删掉注释。否则注释和代码印证不了，到底应该选择相信谁？

Mandated Comments & Javadocs in Nonpublic Code

Mandated Comments的意思是强制的注释。有些不懂的人，往往是Manager，他们不懂技术，他们评价代码好坏的唯一标准就是有没有注释。所以他们也喜欢强调，代码一定要多些注释。更有甚者，每个函数都应该有函数头，为了便于doxygen或javadoc文档话，那要写规范的函数头：

/** 
  *
  * @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) {...}

这样的函数头在接口文档中是有用的，也是必须的。但每一个函数都加上就有点不伦不类了。甚至是Nonpublic的（C里面，可能就是文件里的static函数）。你看这个函数头，就是变量名的简单重复，有什么意义？未来重构的时候想改个变量名，还得改两遍，少改一点就又会给自己或者别人挖坑了。

Journal Comments & Attributions and Bylines

这两者也比较类似，前者是修改记录，后者表示代码的owner。两者都可以由commit记录表示。后者更可以配合issue system，让信息更加完整

* 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);

这种注释见的少了，曾经没有版本管理工具的时候，这种类似变更记录的注释会比较多吧。反正我是基本没见过了。

Noise Comments & Scary Noise

跟前面的redundant comment差不多，就是毫无意义的代码的机械重复，只不过noise和scary noise重复的更加令人发指。

/**
  * Default constructor.
  */ 
  protected AnnualDateRule() { }
  
/**
  * Returns the day of the month.
  *
  * @return the day of the month.
  */
  public int getDayOfMonth() { return dayOfMonth; }

Sometimes you see comments that are nothing but noise. They restate the obvious and provide no new information.

把变量名在注释里再打一遍，是不是noise？scary noise就更烦人了：

    /** The name. */
    private String name;

    /** The version. */
    private String version;

    /** The licenceName. */
    private String licenceName;

    /** The version. */
    private String info;

还是那句话，写这些注释只是让自己自我感觉良好，没有什么更多的价值了。

Don’t Use a Comment When You Can Use a Function or a Variable

这一句应当是我们时刻牢记的，当你想注释的时候，先想想是不是能用函数名和变量名来替换你的注释想表达的意思，如果不行再加注释。
你看这一段注释：

// does the module from the global list <mod> depend on the
// subsystem we are part of?
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem()))

就可以用这一段代码来阐述

ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem))

代码在未来是可以参与重构的，而注释不行，你必须花费额外的精力来维护所有的注释。

Function Headers通常就是这样的一种注释，一个好的名字，的确要好于一个好的header注释。

Position Markers & Closing Brace Comments

这两种有点类似，前者是要凸显某个位置的代码，后者是标记括号的归属者。
前者应当用函数来替换你要凸显处的代码，后者你要缩短大括号中的代码长度。

Commented-Out Code

这个是现在命令禁止的了。因为注释掉的代码，有用，但应该是个暂态，在提交之前应该清理。因为一旦提交，别人或者过一段时间以后作者自己，再也没法说清它到底是有用还是没用。所以确定不需要的代码，应该在提交之前做清理，利用版本管理系统来帮你记住这些变更。

HTML Comments

这种注释我见的也不多，似乎是希望用HTML工具来格式化显示代码注释。
例如：

Nonlocal Information

If you must write a comment, then make sure it describes the code it appears near. Don’t offer systemwide information in the context of a local comment.

这种注释见的也比较少，或者可能之前没太注意。应当值得关注。这就像变量的声明应当离使用它的地方越近越好，道理应该是一样的。

Too Much Information

Don’t put interesting historical discussions or irrelevant descriptions of details into your comments.

这里的意思可能是不要放与代码本身逻辑不太相关的，然后很长的注释。但我认为作者不是一味的反对长篇注释。长篇注释在解释复杂的设计时还是有用的。
例如最近在看golang scheduler设计，这其中好些设计细节，就是靠代码文件篇首的长篇注释阐述的。

Inobvious Connection

The connection between a comment and the code it describes should be obvious.

例如：

/*
 * start with an array that is big enough to hold all the pixels
 * (plus filter bytes), and an extra 200 bytes for header info
 */
 this.pngBytes = new byte[((this.width + 1) * this.height * 3) + 200];

What is a ﬁlter byte?
Does it relate to the +1?
Or to the *3? Both?
Is a pixel a byte? Why 200?

注释隐含了代码未见的信息。在创作代码的时候，可能开发者心里是门儿清的。但你能保证3天以后，几周几年以后还能知道这些隐含的意思吗？你还能猜得出来吗？

总结

首先得说代码注释是有意义的，肯定是有帮助的，但肯定并不那么包治百病。很多时候我们想注释，其实只是想偷懒。或者想写又懒得写的很完整。记住这就是在为自己或别人挖坑。
我建议，在写注释之前，可以先

思考是否可以通过重构，用代码来阐述注释想表达的内容。
如果只是想简单记录，并且回头再做重构，那就在代码里加上TODO/FIXME。

另外，感谢Uncle Bob给了我们一份不错的checklist。我认为以下几种bad comment特别值得注意：

Mumbling
Misleading Comments
Redundant Comments，Noise，Scary Noise
Inobvious Connection
Javadocs in Nonpublic Code