读前：这一章要回答什么

第 12、13 章讲注释，这一章讲名字。两者是一回事的两面：名字也是文档，而且是最短、出现次数最多的文档。每个变量名都会在声明处之外被读到很多次，读者往往只看名字就做出判断，不会每次都回去查注释。

作者把起名字当作"复杂性是一点点累积起来的"的典型例子：一个平庸的名字无伤大雅，但一个系统有成千上万个名字，它们加起来决定了代码好不好读。这一章还藏着一个更深的观点：起名字的难度是设计质量的读数。这和下一章"注释难写说明设计有问题"是一对。到第 18 章讨论"代码一目了然"时，好名字和一致性会被列为最重要的手段中的两种。

核心观点

心智模型：名字在读者脑中圈出一个范围

读者看到一个名字时，脑中会浮现出它可能指的几种东西。名字越泛，这个候选集合越大，读者"按最常见的理解"猜错的机会也越大。好名字的作用是把候选集合缩到只剩一个。

下面的小实验把书中 14.2 节的"孤立测试"变成练习：你只能看到一个变量的声明，先猜它的含义，再看它在代码里实际怎么用。注意观察：一个含糊的名字，是怎样让写下一行代码的人"自然而然"地写出 bug 的。

这些案例都很小，放在一屏里你也许能猜对。真实代码里，声明和使用之间往往隔着几百行、甚至在不同文件里，写下使用那一行的人只能依赖名字。

一个名字两种含义：从名字到类型

书中 14.1 节讲的是作者职业生涯里最难查的一个 bug：一个分布式操作系统的文件系统里，同一个变量名有时指文件内的块号，有时指磁盘上的块号，一处用混了，就把磁盘上一块不相干的数据清零了。前后花了六个月才找到。下面是同一类问题在一个环形消息日志里的样子：

// 消息按递增的序号写入，存放在 slots_[序号 % capacity_]。
class RingLog {
public:
    const Msg& get(uint64_t index) const { return slots_[index % capacity_]; }
    uint64_t head() const;   // 下一条消息的序号
};
// 另一个文件里，缓冲区快照的遍历代码：
for (uint64_t index = 0; index < snapshot.size(); ++index)
    process(log.get(index));   // 这里的 index 是数组下标，不是序号！

const Msg& get(uint64_t seq) const { return slots_[seq % capacity_]; }

for (size_t i = 0; i < snapshot.size(); ++i)
    process(log.get(i));       // get(seq) 却传了 i：一眼就觉得不对

struct Seq { uint64_t value; };      // 消息序号，只增不减
const Msg& get(Seq seq) const { return slots_[seq.value % capacity_]; }
Seq head() const;

for (size_t i = 0; i < snapshot.size(); ++i)
    process(log.get(i));       // 编译错误：size_t 不能隐式转成 Seq

一致性：给项目定一张命名词汇表

精确解决的是"一个名字说没说清楚"，一致性解决的是"读者能不能把在一处学到的东西带到另一处"。书中把它比作复用一个类：读者在一个地方理解了 seq，到了别的文件看到 seq 就能立刻做出正确的假设。三条要求缺一不可，第三条最容易被忽视：用途要定得够窄，窄到所有叫这个名字的变量行为都一样。上面那个 bug 正是第三条被违反了。

在实际项目里，最省事的做法是把高频概念的名字写下来。下面是一个日志存储项目可能有的词汇表：

多余的词

书中 14.5 节列出了三种多余的词，每种在 C++ 代码里都很常见：

std::vector<User> userListVector;   // → users        ：泛名词和类型信息
Connection* pConnObj;               // → conn         ：匈牙利式前缀 + "Obj"
class Segment { size_t segmentSize_; };   // → size_  ：重复类名

作者说自己以前也在名字里放过类型信息，现在不再推荐：IDE 点一下就能看到类型。重复类名有一个例外：如果类里有好几个同类的东西（比如 Segment 既有数据大小又有索引大小），区分它们的词就不是多余的。

边界与反方

练一练

下面三道题来自训练场。本章题库里有 4 道"先写后对照"的改名题，建议都做一遍：起名字这件事，只有动手写才练得出来。

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

动手：项目任务

任务 m07 覆盖第 12～15 章。和本章相关的部分：minikv 的存储层里有几个典型的含糊名字，比如 total_、dead_、count()、handle()。先对每个名字做一次"孤立测试"：只看名字，你能猜出它是什么的总量、什么东西死了、数的是什么、处理的又是什么吗？读懂实际用法后再改名，测试保持全绿。改名时如果发现某个名字怎么也起不好，记下来：那很可能是一处值得重构的设计。

cd project/minikv && make test

自测题

小结与读后一句话

• 名字是一种抽象，也是最常被读到的文档。用"孤立测试"检验它：只看名字能不能猜对。
• 精确：避免泛泛的词，布尔值用谓词；但也别比抽象本身更具体。
• 一致：同一用途同一个名字，这个名字不做他用，用途窄到所有同名变量行为一致。
• 删掉不提供信息的词；名字长度随声明和使用的距离增长；可读性由读者裁决。
• 名字难起，往往是设计不干净的信号；容易混淆的数值，用不同的类型比用不同的名字更可靠。

第 15 章把同样的思路用到注释上：如果一个方法或变量的注释怎么也写不短，那也是设计在报警。两章合起来，就是在写实现之前，用名字和注释来检验设计。

读后一句话：用你自己的话写下这一章最重要的一个观点，最好附上一个你最近改过（或想改）的名字。