读前：这一章要回答什么

这一章开启了全书的第四部分：注释与命名（第 12～15 章，第 16 章讲注释的维护）。它是一篇"辩护词"：作者逐一反驳开发者不写注释时最常用的四个借口，然后说明好注释能带来什么。具体怎么写，留给第 13 章。

如果你认真读了第 4 章，这一章的核心论证其实已经埋好了伏笔：接口分正式部分（签名）和非正式部分（行为、约束、副作用），而非正式部分只能用注释写。作者在这里把这条线索推到结论：没有注释，就没有抽象。注释不是锦上添花的文档工作，而是模块设计的一部分。

核心观点

心智模型：设计者脑子里的信息去哪了

写代码时，你脑子里装着大量信息：这个函数在什么情况下被调用、返回 0 代表什么、为什么这里要多判断一次、那个奇怪的常量从哪来。代码只能装下其中一部分。剩下的，要么写进注释，要么随着你忘记而消失，后来的人只能重新推导或者猜。

注意第三条路里有"几周后的你"。作者特别指出，即使是原作者自己，离开一段代码几周后也会忘掉很多设计细节。

四个借口与作者的回应

一个原创例子：声明到底缺了什么

书中 12.1 节用一个只有起止两个参数的取子串函数说明：光看声明，你连"终点含不含"都不知道。下面是一个后端开发里常见的、同样性质的例子：分布式锁的客户端接口。

class LockClient {
public:
    bool tryLock(const std::string& name, std::chrono::seconds ttl);
    void unlock(const std::string& name);
};

// 基于协调服务的分布式互斥锁客户端。每个 name 是一把独立的锁；
// 同一时刻全集群最多一个持有者。线程安全。
class LockClient {
public:
    // 尝试获取锁，不等待：已被持有时立即返回 false。
    // 成功后锁最多保持 ttl；到期自动释放，期间进程崩溃也一样。
    // 需要更久时，在到期前再调用一次 tryLock 续期（自己已持有时返回 true）。
    // 与协调服务通信失败时抛 LockServiceError，而不是返回 false。
    bool tryLock(const std::string& name, std::chrono::seconds ttl);

    // 释放锁。如果锁已经过期、或已被别人持有，什么也不做。
    void unlock(const std::string& name);
};

换一个角度看：如果没有这些注释，每个使用者都得去读实现、甚至读协调服务的文档，才能回答上面那串问题。那么 LockClient 就算接口再短，也没有替任何人隐藏复杂性，第 4 章意义上的"深"也就无从谈起。

边界与反方

练一练

下面三道题来自训练场：一道看"用方法名代替注释"会产生什么，一道比较长方法名和一条注释，一道请你亲手列出声明表达不了的信息。

再加一道，取材于读者讨论组（对应上面"边界与反方"里的"讨论组"一栏）：

动手：项目任务

第 12～15 章合起来对应 minikv 的任务 m07（注释与命名）。这一章只负责说服你"值得做"，具体的做法在第 13 章。建议读完第 13 章后再开始，任务说明见 m07 任务页，第 13 章页面里也有任务入口。

自测题

小结与读后一句话

• 注释保存设计者脑中、代码装不下的信息：接口的非正式部分、结果含义、设计理由、调用条件。
• 没有注释就没有抽象：使用者必须读实现时，复杂性就完全暴露了。
• 四个借口：自解释代码（不成立）、没时间（约 10% 的投资）、会过期（可管理）、都没用（最有道理，但可以解决）。
• 好注释减轻认知负担和未知的未知，讲清依赖、消除模糊性；它不减少变更放大。
• 作者同意好设计能减少注释（尤其方法体内的），但不同意"注释是失败"。

第 13 章回答这一章留下的问题：什么样的注释才不是"没用的注释"？答案的核心是一句话：注释应该描述代码里看不出来的东西。

读后一句话：你最常用（或最常听到）的是哪个借口？读完这一章，你会怎么回应它？