读前：这一章要回答什么

第 2 章说复杂性有两个根源：依赖和模糊性（obscurity）。第 4～11 章主要对付依赖；第 12～17 章从注释、命名、一致性入手对付模糊性。这一章把这条线收尾：给"不模糊"一个可操作的定义，即代码一目了然（obvious），读得快，而且第一眼的猜测是对的。

这一章提出了全书最后一个红旗"代码不明显"，和第 14 条设计原则"为易读而设计，而不是为易写而设计"。后者是一个很实用的裁判标准：几乎每一个"写起来方便"的捷径（返回 std::pair、加一个 bool 参数、在构造函数里顺手启动点什么）都是把成本从写的人转嫁给了以后所有读的人。

核心观点

心智模型：读者缺了什么信息

作者在 18.3 节换了一个角度：代码不明显，通常意味着读者缺少某条重要信息。于是"让代码明显"就变成"让读者拿到信息"，而拿到信息有三种方式，代价和效果完全不同：

这个排序和全书一脉相承：第 ① 种就是第 4～10 章的深模块、信息隐藏和"把错误定义为不存在"；第 ② 种是第 17 章的一致性；第 ③ 种是第 12～15 章的注释和命名。注释是兜底手段，不是首选。

试一试：你的第一眼猜对了吗？

下面的小工具只给你看调用处的一行代码，就像你在评审一个 diff 时看到的那样。先凭第一眼选一个猜测，再看真相和改法。

你猜错了不说明你粗心：调用处本来就没有给出足够的信息。每个例子的改法都是把信息搬到读者第一眼能看到的地方，或者让它变得不必要。

让代码更明显：名字、一致性、空白、注释

名字和一致性前两章已经讲过，这里不再展开。书中另外讲了空白的作用（用 Javadoc 参数说明和一段内存分配代码举例，见 18.1 节）。空白有三个层次：注释里用缩进区分条目、函数里用空行分块、语句里用空格分出结构。下面是一个日志恢复函数，逻辑完全相同：

int LogReader::recover(){
    uint64_t off=0;Header h;
    while(readHeader(off,&h)==0){
        if(h.magic!=kMagic||h.len>kMaxRecord)break;
        if(crc32(payload(off,h.len))!=h.crc)break;
        index_.put(h.key,off);off+=sizeof(h)+h.len;
    }
    truncateAt(off);return 0;
}

// 从头扫描日志，重建内存索引。遇到第一条不完整或损坏的记录就停下，
// 把它和之后的内容截掉：它们来自崩溃时没写完的追加。
int LogReader::recover() {
    uint64_t off = 0;
    Header h;
    while (readHeader(off, &h) == 0) {
        // 头部不合法：到了上次崩溃时写了一半的位置。
        if (h.magic != kMagic || h.len > kMaxRecord) break;

        // 头部合法但内容校验失败：同样视为写了一半。
        if (crc32(payload(off, h.len)) != h.crc) break;

        index_.put(h.key, off);
        off += sizeof(h) + h.len;
    }

    // off 之后的内容都不可信。
    truncateAt(off);
    return 0;
}

当不明显的写法无法避免时（例如为了性能），作者要求用注释补偿：站在读者的位置，想清楚对方会在哪里困惑、哪条信息能消除困惑，然后只写那条信息。

让代码不明显的四类写法（C++ 版）

1. 事件驱动：谁在什么时候调用我？

事件驱动的代码里，处理函数从不被直接调用，而是由事件模块通过函数指针、std::function 或虚函数间接调用。你在处理函数里找不到调用者，在事件模块里找到调用点也看不出会调到哪个函数，因为那取决于运行时注册了什么。

void Server::start() {
    loop_.watch(listenFd_, Event::Readable, [this] { onAccept(); });
    loop_.every(std::chrono::seconds(1), [this] { reapIdle(); });
}

// …… 四百行之后 ……

// 关闭空闲超过 idleTimeout_ 的连接。
// 由事件循环每秒调用一次，运行在 I/O 线程里，和 onAccept/onReadable
// 不会并发执行，所以这里可以不加锁地修改 conns_。
void Server::reapIdle() {
    auto now = Clock::now();
    std::erase_if(conns_, [&](auto& kv) { return now - kv.second.lastActive > idleTimeout_; });
}

第 9～10 行就是作者建议的补偿：在每个处理函数的接口注释里写明它在什么时候、被谁、在哪个线程调用。没有这两行，读者读到 reapIdle 时最想问的"这里不加锁安全吗？"就没有答案。作者并没有说事件驱动不好，它在网络服务里几乎无法替代；作者说的是用了就要补上文档。

2. 通用容器：.first 是什么？

std::pair、std::tuple 写起来很方便，一个返回值就能带回好几样东西。问题是元素的名字是通用的：first、second、std::get<2>，读者从名字里得不到任何含义。作者的结论是：最好不要用通用容器，需要组合值就定义一个专门的类或结构体。

// 查找 key 在日志里的最新记录。
std::optional<std::tuple<uint64_t, uint32_t, bool>>
Index::locate(const Key& key) const;

// 调用者（另一个文件里）：
auto r = index_.locate(key);
if (!r || std::get<2>(*r)) return -ENOENT;
return readAt(std::get<0>(*r), std::get<1>(*r), out);

// 一个键在日志里最新一条记录的位置。
struct Location {
    uint64_t offset;     // 记录在日志文件中的起始偏移
    uint32_t length;     // 记录总长度，含头部
    bool     tombstone;  // 这条记录是删除标记：键已被删除
};
// key 从未写入过时返回 std::nullopt。
std::optional<Location> Index::locate(const Key& key) const;

// 调用者：
auto loc = index_.locate(key);
if (!loc || loc->tombstone) return -ENOENT;
return readAt(loc->offset, loc->length, out);

software should be designed for ease of reading, not ease of writing.— 第 18.2 节

这就是第 14 条原则的来历：通用容器对写的人很方便，却让之后所有读的人困惑。同样的道理，本站补充一个 C/C++ 里比 pair 还常见的例子：bool 参数。

void Store::flush(bool sync, bool compact);

// 调用处：
store.flush(true, false);

enum class Durability { Buffered, Fsync };
void Store::flush(Durability d);
void Store::compact();     // 原来的第二个 bool 本来就是另一件事

// 调用处：
store.flush(Durability::Fsync);

3. 声明的类型和实际的类型不一致

书中的例子是 Java 里把变量声明成接口类型 List、实际分配 ArrayList。C++ 里对应的情形是：成员声明成抽象基类的指针，实际总是某一个具体实现，而代码依赖了那个具体实现的特性。

class Dispatcher {
    // ……
    std::unique_ptr<TaskQueue> queue_;
};

Dispatcher::Dispatcher() : queue_(std::make_unique<MpscLockFreeQueue>()) {}

// 在多个工作线程里并发调用：
void Dispatcher::submit(Task t) {
    queue_->push(std::move(t));   // 没加锁：依赖 MpscLockFreeQueue 是多生产者安全的
}

读者看到第 3 行的声明，会以为这里只依赖 TaskQueue 的接口；但 TaskQueue 的接口并不保证线程安全，第 10 行能工作，全靠构造函数里那个具体类型。作者的建议是让声明和分配一致：直接把成员声明成 std::unique_ptr<MpscLockFreeQueue>（或者干脆是一个值成员）。本站补充另一种同样有效的改法：把"多生产者安全"写进 TaskQueue 的接口约定，让所有实现都必须满足。两种改法的共同点是：读者在声明处就能看到代码真正依赖的东西。

4. 违反读者预期的代码

书中的例子是一个 main 函数返回后程序却不退出，因为某个构造函数悄悄起了线程。C++ 读者对构造函数也有一个普遍的预期：它初始化这个对象，不去改动进程级别的状态。下面的构造函数打破了这个预期：

int main(int argc, char** argv) {
    Config cfg = Config::load(argv[1]);
    Logger log(cfg.logPath());
    ConfigWatcher watcher(argv[1], &cfg);   // 构造函数里调用了 sigaction(SIGHUP, …)

    // 半年后，另一位同事为了支持日志轮转加了这一行：
    std::signal(SIGHUP, [](int) { Logger::reopenAll(); });

    return Server(cfg).run();
}

第 7 行的作者看不到第 4 行在构造时装了信号处理器，于是悄悄覆盖了它，配置热加载从此失效，而且没有任何报错。作者对这类代码的建议是：在构造函数的接口注释里写明这种行为；如果它足够出人意料，在调用处（这里是 main）也加一行简短的注释。作者的原则是：代码遵守读者预期的约定时最明显；不遵守时，就必须把这种行为写清楚。本站补充：能做到的话，更好的办法是让副作用变成显式调用，例如 watcher.reloadOn(SIGHUP);，让 main 里所有信号处理都看得见，这就从"把信息写在读者眼前"升级成了"符合读者预期"。

边界与反方

练一练

下面三道题来自训练场。本章的题大多是"识红旗"：先只凭第一眼读代码，再看自己漏掉了什么。

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

动手：项目任务

minikv 是一个故意按"战术式"风格写成的迷你键值存储。任务 m08 对应本章和第 20 章：在 minikv 里找出让人第一眼就猜错的代码，例如 bulk(s, true, true) 这种看不出含义的 bool 参数、用 std::pair<bool, std::string> 带回来的返回值、一个"只是查询"却会悄悄改统计数字的方法，把它们改得一目了然；性能相关的部分留到第 20 章再做。改之前先写下你第一眼的猜测，改完请一位没看过这段代码的人读一遍，看对方的第一眼猜测是否正确。

cd project/minikv && make test

自测题

小结与读后一句话

• 代码一目了然 = 读得快，而且第一眼的猜测正确；明显与否由读者（评审者）判断。
• 让代码更明显：好名字、一致性、恰当的空白；无法避免不明显时，用注释补上缺失的信息。
• 让代码不明显：事件驱动、通用容器、声明类型与实际类型不一致、违反读者预期的行为。
• 为易读而设计，而不是为易写而设计：写的人多花几分钟，换来所有读者少花时间。
• 三种给读者信息的方式：减少所需信息（最好）、利用已有信息、在代码里呈现信息。

到这里，全书的 14 个红旗都已出现。下一章（软件开发趋势）换一个视角：拿前面学到的原则去评价面向对象、敏捷、测试驱动开发、设计模式等流行做法，看它们到底是减少还是增加了复杂性。

读后一句话：找一段你最近在评审里被问过"这是什么意思"的代码，写下当时读者缺了什么信息，以及三种方式里哪一种最适合补上它。