读前：这一章要回答什么

第 12、13 章回答了"为什么要写注释"和"注释该写什么"。但即使认同这两章，大多数人仍然会把注释留到最后。这一章只讲一件事：写注释的时机。作者的主张是把它挪到最前面，在写实现之前先用注释把抽象写出来。

这一章很短，却是第 4 章"深模块"和第 13 章"接口注释"的交汇点：接口注释写出来有多长，几乎就是接口有多复杂的直接读数。所以先写注释不只是个文档习惯，而是一种廉价的设计评审：在一行实现都没有的时候，就能看出这个抽象深不深。它和第 11 章"设计两次"一样，都是在设计阶段多花一点时间的方法。

核心观点

心智模型：问题在哪一步被发现

两种做法写出来的注释，篇幅可能差不多。真正的差别在于"接口设计得别扭"这件事在哪一步被发现，以及发现时要改多少东西。

Comments serve as a canary in the coal mine of complexity.— 第 15.3 节

矿井里的金丝雀会比人更早对毒气起反应。注释也一样：在接口复杂到伤害调用者之前，写注释的人会先感到别扭。前提是你在设计阶段就写，并且认真写完整。

跟着做：用注释设计一个类

读这一章最好的方式是真的试一次。下面按书中 15.2 节的顺序走一遍，每一步先在文本框里写（自动保存在本机），写完再展开参考。不必追求和参考一致，重要的是你在写的过程中被迫做出了哪些决定。

// ① 类注释：？
class UploadSession {
public:
    // ② ？
    UploadSession(std::string uploadId, uint64_t totalBytes, uint32_t chunkBytes);
    // ③ ？
    void putChunk(uint32_t index, std::span<const std::byte> data);
    // ④ ？
    std::vector<uint32_t> missingChunks() const;
    // ⑤ ？
    std::filesystem::path commit();
};

// 一次可续传的分块上传。客户端可以按任意顺序上传各块，也可以重传；
// 所有块到齐后调用 commit() 得到拼好的完整文件。
// 不是线程安全的：同一个 uploadId 同一时刻只应由一个线程操作。

// ② totalBytes 是文件总大小；除最后一块外，每块都是 chunkBytes 字节。
//    块的个数为 ceil(totalBytes / chunkBytes)，下标从 0 开始。

// ③ 保存第 index 块。重传同一块时，新数据覆盖旧数据。
//    index 越界、或 data 长度不等于该块应有的长度（最后一块可能较短）时
//    抛 std::invalid_argument，已收到的数据不受影响。
//    commit() 成功之后再调用，抛 std::logic_error。

// ④ 还没收到的块的下标，升序。客户端断线重连后据此决定从哪里续传。

// ⑤ 把所有块拼成一个文件，返回它的路径；之后这个对象不能再使用。
//    仍有块缺失时抛 std::logic_error，对象状态不变，可以继续 putChunk()。

// ？
int put(uint32_t index, std::span<const std::byte> data, bool isLast, bool dryRun);

std::filesystem::path dir_;     // 本次上传专用的临时目录，第 i 块存为 dir_/i
std::vector<bool> received_;    // received_[i] 为真表示第 i 块已完整写入磁盘
uint32_t numReceived_ = 0;      // received_ 中为真的个数，等于块数时才能 commit
bool committed_ = false;        // commit() 成功后为真，此后所有操作都抛 logic_error

最后一步是写方法体，并在需要的地方加实现注释。写的过程中如果发现还需要新的方法或变量，照样先写注释、再写代码。这样走一遍，代码写完的那一刻，注释也已经写完，没有欠账。

一个原创例子：事后补的注释 vs 先写的注释

同一个方法，两份注释。第一份是功能上线后补文档时加的，第二份是设计时、方法体还空着的时候写的。

// 检查 activeSegment_ 的大小是否大于 maxSegmentBytes_，
// 如果是就调用 sealSegment()，然后新建一个 segment。
void LogStore::rollIfNeeded();

// 当前段写满时把它封存（之后只读、可以被压缩和删除），并开启新段。
// 每次追加写之后调用；未写满时什么也不做。
// 封存不会等待落盘：需要持久化保证的调用者应在之后调用 sync()。
void LogStore::rollIfNeeded();

两份注释差不多长，写第二份也不比第一份多花时间。代价在别处：写第二份时你必须已经想清楚这些问题。这正是作者想要的效果。如果你发现自己想不清楚，那恰好说明还不该动手写实现。

边界与反方

练一练

下面三道题来自训练场。先自己判断再看解析，答题记录会进入间隔复习。

动手：项目任务

任务 m07 覆盖第 12～15 章。和本章相关的部分是它的最后一步：给 minikv 新增 RENAME src dst 命令。严格按"先写注释"的顺序来：在写任何实现之前，先写出 Store::rename 的接口注释。写的时候你会被迫回答几个设计问题：src 不存在怎么办？dst 已经存在呢？src 和 dst 相同呢？如果进程恰好在写完两条日志记录之间崩溃，重启后会看到什么？把答案写进注释，再动手实现。

cd project/minikv && make test

自测题

小结与读后一句话

• 推迟的注释往往没写，或者写得差：复述代码、遗漏设计信息。
• 先写类注释和方法接口注释，再写成员变量，最后写实现；写完代码时注释也写完了。
• 注释是设计工具：抽象要靠注释才能完整写下来，写下来才能在实现前审查。
• 完整的注释写不短，是设计有问题的信号（难以描述）；短而不完整的注释不算数。
• 成本很低：注释只占开发时间的一小部分，而更早稳定的抽象能减少返工。

第 15 章讲的是写新代码。可大多数时间我们在改旧代码，第 16 章接着回答：修改代码时怎样保持战略式的心态，怎样让注释不随修改而过时。

读后一句话：用你自己的话写下这一章最重要的一个观点，最好结合你最近写过的某个类。