读前：这一章要回答什么

前面十几章大多在讲"第一次把东西设计好"。但作者在本章开头提醒：一个成熟系统的设计，更多是由它一路上的修改决定的，而不是由最初的构想决定的。大多数程序员大部分时间都在改别人（或很久以前的自己）写的代码，所以这一章讨论的其实是日常工作里最常见的场景。

本章分两部分。第一部分（16.1 节）把第 3 章的战略式编程用到修改代码上：每次修改都是一次小投资的机会。第二部分（16.2～16.6 节）是一组很具体的技巧，让第 12～15 章辛苦写出来的注释不会随着修改而过时。它们都可以直接用在下一次代码评审里。

核心观点

心智模型：设计质量随修改的走向

If you're not making the design better, you are probably making it worse.— 第 16.1 节

左图是这句话的直观版本。最小改动的每一步看起来都无害，但它们只朝一个方向累积。战略式修改每次都要多花一点时间（图中的小下探），换来的是总体向上的趋势。右图对应 16.2 节的一条规则：注释离它描述的代码越远，就越应该抽象，这样小的代码改动不会让它失效。

一个原创例子：同一个 bug 的两种修法

电商系统里，促销商品的价格偶尔显示成旧价。排查发现：促销引擎直接写数据库里的价格表，绕过了价格服务，所以价格服务的缓存不会失效。

Price PriceService::get(ItemId id) {
    const Item& item = catalog_.item(id);
    if (item.onPromotion)                 // 促销价不走缓存
        return db_.loadPrice(id);
    if (auto p = cache_.find(id)) return *p;
    Price p = db_.loadPrice(id);
    cache_.put(id, p);
    return p;
}
// 提交信息：促销引擎直接写库，缓存不会失效，所以促销商品先绕过缓存。

// 商品价格的唯一写入入口。所有改价都必须经过这里：绕过它直接写
// 价格表，缓存中的旧价格就不会失效。读取请用 get()，它总是走缓存。
void PriceStore::update(ItemId id, Price p) {
    db_.savePrice(id, p);
    cache_.invalidate(id);
}

Price PriceStore::get(ItemId id) {
    if (auto p = cache_.find(id)) return *p;
    Price p = db_.loadPrice(id);
    cache_.put(id, p);
    return p;
}
// 同一次提交中：促销引擎改为调用 PriceStore::update()，不再直接写价格表。

如果促销团队这周确实没法配合，就该问那个问题：在当前约束下，最干净的做法是什么？比如让价格服务订阅数据库的变更通知来做失效，这样不需要改促销引擎，读取路径也不用加特殊情况；或者先上最小改动，但把"绕过缓存"的原因写进代码，并约好下个迭代回来做正确的修法。

实现注释：放到最小的范围里

16.2 节的另一条规则针对方法内部：不要在方法开头写一大段注释描述所有细节，而是把每条注释"往下推"，推到恰好覆盖它所说代码的最小范围。方法开头可以保留一段只讲整体思路的概述：

void Compactor::run() {
    // 分三步：选出要合并的段 → 合并成一个新段 → 切换索引并删除旧段。
    // 任何一步失败都只影响新段，旧段在第三步之前一直完整可用。

    // 只挑垃圾比例超过阈值的段；太新的段可能还有进行中的读者，跳过。
    std::vector<Segment*> victims = pickVictims(minGarbageRatio_);
    ...
    // 新段先写到临时文件，fsync 之后才改名，保证崩溃后不会留下半个段。
    ...
    // 先切换索引再删旧段：顺序反过来的话，读者可能查到已删除的段。
    ...
}

改第三步的人一定会看到第三步上方的注释，却未必会回到方法开头去更新一大段描述。概述只讲结构，小改动不会让它失效。

跟着做：提交前看一遍 diff

16.5 节的建议最容易执行：提交前花几分钟把整个 diff 过一遍。下面是一次"把缓存容量从条目数改成字节数"的提交。先自己找问题，写下来，再展开参考。（提示：至少有 5 处，大多和注释有关。）

  // cache.cc
  // 当缓存中的条目数超过 capacity_ 时，淘汰最久未使用的条目。
  void Cache::evictIfNeeded() {
-     while (lru_.size() > capacity_) {
+     while (usedBytes_ > capacityBytes_) {
+         fprintf(stderr, "evict used=%zu\n", usedBytes_);
          Entry& victim = lru_.back();
+         usedBytes_ -= victim.value.bytes();
          map_.erase(victim.key);
          lru_.pop_back();
      }
+     // TODO: 大对象单独处理
  }

  void Cache::put(Key k, Value v) {
      ...
+     usedBytes_ += v.bytes();
+     // evictIfNeeded() 会按字节数淘汰最久未使用的条目，
+     // 直到 usedBytes_ 不超过 capacityBytes_。
      evictIfNeeded();
  }

  // cache.h
- explicit Cache(size_t capacity);        // capacity：最多保存的条目数
+ explicit Cache(size_t capacityBytes);   // capacity：最多保存的条目数

边界与反方

练一练

本章没有新的红旗。训练题都是"评审一份 diff"的场景，用到的是前面各章的红旗，正好检验你在修改代码时能不能认出它们。

自测题

小结与读后一句话

• 系统的设计主要由一次次修改决定。改代码时也要战略式：改完后，结构应该像是从一开始就为这个改动设计的。
• 每次修改都顺手改进一点设计；被约束逼着妥协时，问"这是当前约束下最干净的设计吗"，并安排时间回来。
• 注释贴着代码放：接口注释挨着方法体，实现注释下沉到最小范围；离代码越远越抽象。
• 将来需要的信息写进代码，不只写在提交信息里；每个设计决定只记录一次，别处引用它。
• 提交前看一遍 diff：文档跟上了吗？有没有调试代码和 TODO？

第 17 章讨论一致性。它和本章是同一个问题的两面：修改代码时最容易破坏的，就是系统里原有的约定。新代码要遵守旧约定，想改约定，就得把旧代码一起改过来。

读后一句话：用你自己的话写下这一章最重要的一个观点，最好结合你最近一次提交或评审。