如何精准命名

不精准的命名

我们先来看一段代码：

　　public void processChapter(long chapterId) {
　　  Chapter chapter = this.repository.findByChapterId(chapterId);
　　  if (chapter == null) {
　　    throw new IllegalArgumentException("Unknown chapter [" + chapterId + "]");
　　  }
　　  chapter.setTranslationState(TranslationState.TRANSLATING);
　　  this.repository.save(chapter);
　　}

这是一段看上去还挺正常的代码，甚至以很多团队的标准来看，这段代码写得还不错。但如果我问你，这段代码是做什么的。你就需要调动全部注意力，去认真阅读这段代码，找出其中的逻辑。经过阅读我们发现，这段代码做的就是把一个章节的翻译状态改成翻译中。

问题来了，为什么你需要阅读这段代码的细节，才能知道这段代码是做什么的？

问题就出在函数名上。这个函数的名字叫 processChapter（处理章节），这个函数确实是在处理章节，但是，这个名字太过宽泛。如果说“将章节的翻译状态改成翻译中”叫做处理章节，那么“将章节的翻译状态改成翻译完”是不是也叫处理章节呢？“修改章节内容”是不是也叫处理章节呢？换句话说，如果各种场景都能够叫处理章节，那么处理章节就是一个过于宽泛的名字，没有错，但不精准。

这就是一类典型的命名问题，从表面上看，这个名字是有含义的，但实际上，它并不能有效地反映这段代码的含义。如果说我在做的是一个信息处理系统，你根本无法判断，我做是一个电商平台，还是一个图书管理系统，从沟通的角度看，这就不是一个有效的沟通。要想理解它，你需要消耗大量认知成本，无论是时间，还是精力。

命名过于宽泛，不能精准描述，这是很多代码在命名上存在的严重问题，也是代码难以理解的根源所在。

或许这么说你的印象还是不深刻，我们看看下面这些词是不是经常出现在你的代码里：data、info、flag、process、handle、build、maintain、manage、modify 等等。这些名字都属于典型的过于宽泛的名字，当这些名字出现在你的代码里，多半是写代码的人当时没有想好用什么名字，就开始写代码了。我相信，只要稍微仔细想想，类似的名字你一定还能想出不少来。

描述意图而非细节

回到前面那段代码上，如果它不叫“处理章节”，那应该叫什么呢？首先，命名要能够描述出这段代码在做的事情。这段代码在做的事情就是“将章节修改为翻译中”。那是不是它就应该叫 changeChapterToTranslating 呢？

不可否认，相比于“处理章节”，changeChapterToTranslating 这个名字已经进了一步，然而，它也不算是一个好名字，因为它更多的是在描述这段代码在做的细节。我们之所以要将一段代码封装起来，一个重要的原因就是，我们不想知道那么多的细节。如果把细节平铺开来，那本质上和直接阅读代码细节差别并不大。

所以，一个好的名字应该描述意图，而非细节。

就这段代码而言， 我们为什么要把翻译状态修改成翻译中，这一定是有原因的，也就是意图。具体到这里的业务，我们把翻译状态修改成翻译中，是因为我们在这里开启了一个翻译的过程。所以，这段函数应该命名 startTranslation。

　　public void startTranslation(long chapterId) {
　　  Chapter chapter = this.repository.findByChapterId(chapterId);
　　  if (chapter == null) {
　　    throw new IllegalArgumentException("Unknown chapter [" + chapterId + "]");
　　  }
　　  chapter.setTranslationState(TranslationState.TRANSLATING);
　　  this.repository.save(chapter);
　　}

用技术术语命名

我们再来看一段代码：

　　List<Book> bookList = service.getBooks();

可以说这是一段常见得不能再常见的代码了，但这段代码却隐藏另外一个典型得不能再典型的问题：用技术术语命名。

这个 bookList 变量之所以叫 bookList，原因就是它声明的类型是 List。这种命名在代码中几乎是随处可见的，比如 xxxMap、xxxSet。

这是一种不费脑子的命名方式，但是，这种命名却会带来很多问题，因为它是一种基于实现细节的命名方式。

我们都知道，编程有一个重要的原则是面向接口编程，这个原则从另外一个角度理解，就是不要面向实现编程，因为接口是稳定的，而实现是易变的。虽然在大多数人的理解里，这个原则是针对类型的，但在命名上，我们也应该遵循同样的原则。为什么？我举个例子你就知道了。

比如，如果我发现，我现在需要的是一个不重复的作品集合，也就是说，我需要把这个变量的类型从 List 改成 Set。变量类型你一定会改，但变量名你会改吗？这还真不一定，一旦出现遗忘，就会出现一个奇特的现象，一个叫 bookList 的变量，它的类型是一个 Set。这样，一个新的混淆就此产生了。

那有什么更好的名字吗？我们需要一个更面向意图的名字。其实，我们在这段代码里真正要表达的是拿到了一堆书，所以，这个名字可以命名成 books。

　　List<Book> books = service.getBooks();

也许你发现了，这个名字其实更简单，但从表意的程度上来说，它却是一个更有效的名字。

虽然这里我们只是以变量为例说明了以技术术语命名存在的问题，事实上，在实际的代码中，技术名词的出现，往往就代表着它缺少了一个应有的模型。

比如，在业务代码里如果直接出现了 Redis：

　　public Book getByIsbn(String isbn) {
　　  Book cachedBook = redisBookStore.get(isbn);
　　  if (cachedBook != null) {
　　    return cachedBook;
　　  }
　　  Book book = doGetByIsbn(isbn);
　　  redisBookStore.put(isbn, book);
　　  return book;
　　}

通常来说，这里真正需要的是一个缓存。Redis 是缓存这个模型的一个实现：

　　public Book getByIsbn(String isbn) {
　　  Book cachedBook = cache.get(isbn);
　　  if (cachedBook != null) {
　　    return cachedBook;
　　  }

　　  Book book = doGetByIsbn(isbn);
　　  cache.put(isbn, book);
　　  return book;
　　}

再进一步，缓存这个概念其实也是一个技术术语，从某种意义上说，它也不应该出现在业务代码中。这方面做得比较好的是 Spring。使用 Spring 框架时，如果需要缓存，我们通常是加上一个 Annotation（注解）：

　　@Cacheable("books")
　　public Book getByIsbn(String isbn) {

　　  ...

　　}

程序员之所以喜欢用技术名词去命名，一方面是因为，这是大家习惯的语言，另一方面也是因为程序员学习写代码，很大程度上是参考别人的代码，而行业里面优秀的代码常常是一些开源项目，而这些开源项目往往是技术类的项目。在一个技术类的项目中，这些技术术语其实就是它的业务语言。但对于业务项目，这个说法就必须重新审视了。

如果这个部分的代码确实就是处理一些技术，使用技术术语无可厚非，但如果是在处理业务，就要尽可能把技术术语隔离开来。

用业务语言写代码

无论是不精准的命名也好，技术名词也罢，归根结底，体现的是同一个问题：对业务理解不到位。

我在《[10x 程序员工作法]》专栏中曾经说过，编写可维护的代码要使用业务语言。怎么才知道自己的命名是否用的是业务语言呢？一种简单的做法就是，把这个词讲给产品经理，看他知不知道是怎么回事。

从团队的角度看，让每个人根据自己的理解来命名，确实就有可能出现千奇百怪的名字，所以，一个良好的团队实践是，建立团队的词汇表，让团队成员有信息可以参考。

团队对于业务有了共同理解，我们也许就可以发现一些更高级的坏味道，比如说下面这个函数声明：

　　public void approveChapter(long chapterId, long userId) {

　　  ...

　　}

这个函数的意图是，确认章节内容审核通过。这里有一个问题，chapterId 是审核章节的 ID，这个没问题，但 userId 是什么呢？了解了一下背景，我们才知道，之所以这里要有一个 userId，是因为这里需要记录一下审核人的信息，这个 userId 就是审核人的 userId。

你看，通过业务的分析，我们会发现，这个 userId 并不是一个好的命名，因为它还需要更多的解释，更好的命名是 reviewerUserId，之所以起这个名字，因为这个用户在这个场景下扮演的角色是审核人（Reviewer）。

　　public void approveChapter(long chapterId, long reviewerUserId) {

　　  ...

　　}

从某种意义上来说，这个坏味道也是一种不精准的命名，但它不是那种一眼可见的坏味道，而是需要在业务层面上再进行讨论，所以，它是一种更高级的坏味道。

我初入职场的时候，有一次为一个名字陷入了沉思，一个工作经验丰富的同事对此的评价是：你开始进阶了。确实，能够意识到自己的命名有问题，是程序员进阶的第一步。

总结

错误命名：

• 宽泛的命名
• 用技术术语命名

命名遵循的原则

• 描述意图，而非细节
• 命名中出现技术名词，往往是它缺少一个模式
• 使用业务语言

关于英文命名

违反语法规则的命名

我们来看一段代码：

　　public void completedTranslate(final List<ChapterId> chapterIds) {

　　  List<Chapter> chapters = repository.findByChapterIdIn(chapterIds);
　　  chapters.forEach(Chapter::completedTranslate);
　　  repository.saveAll(chapters);

　　}

初看之下，这段代码写得还不错，它要做的是将一些章节的信息标记为翻译完成。似乎函数名也能反映这个意思，但仔细一看你就会发现问题。

因为 completedTranslate 并不是一个正常的英语函数名。从这个名字你能看出，作者想表达的是“完成翻译”，因为是已经翻译完了，所以，他用了完成时的 completed，而翻译是 translate。这个函数名就成了 completedTranslate。由此，你可以看到，作者已经很用心了，但遗憾的是，这个名字还是起错了。

一般来说，常见的命名规则是：类名是一个名词，表示一个对象，而方法名则是一个动词，或者是动宾短语，表示一个动作。

以此为标准衡量这个名字，completedTranslate 并不是一个有效的动宾结构。如果把这个名字改成动宾结构，只要把“完成”译为 complete，“翻译”用成它的名词形式 translation 就可以了。所以，这个函数名可以改成 completeTranslation：

　　public void completeTranslation(final List<ChapterId> chapterIds) {

　　  List<Chapter> chapters = repository.findByChapterIdIn(chapterIds);
　　  chapters.forEach(Chapter::completeTranslation);
　　  repository.saveAll(chapters);

　　}

这并不是一个复杂的坏味道，但这种坏味道在代码中却时常可以见到，比如，一个函数名是 retranslation，其表达的意图是重新翻译，但作为函数名，它应该是一个动词，所以，正确的命名应该是 retranslate。

其实，只要你懂得最基本的命名要求，知道最基本的英语规则，就完全能够发现这里的坏味道。比如，判断函数名里的动词是不是动词，宾语是不是一个名词？这并不需要英语有多么好。自己实在拿不准的时候，你就把这个词放到字典网站 (opens new window)中查一下，确保别用错词性就好。

对于大多数国内程序员来说，字典网站 (opens new window)是我们的好朋友，是我们在写程序过程中不可或缺的一个好伙伴。不过，有些人使用字典网站 (opens new window)也会很随意。

不准确的英语词汇

有一次，我们要实现一个章节审核的功能，一个同事先定义出了审核的状态：

　　public enum ChapterAuditStatus {

　　    PENDING,
　　    APPROVED,
　　    REJECTED;
　　}

你觉得这段代码有问题吗？如果看不出来，一点都不奇怪。如果你用审核作为关键字去字典网站 (opens new window)上搜索，确实会得到 audit 这个词。所以，审核状态写成 AuditStatus 简直是再正常不过的事情了。

然而，看到这个词的时候，我的第一反应就是这个词好像不太对。因为之前我实现了一个作品审核的功能，不过我写的定义是这样的：

　　public enum BookReviewStatus {

　　    PENDING,
　　    APPROVED,
　　    REJECTED;

　　}

抛开前缀不看，同样是审核，一个用了 audit，一个用了 review。这显然是一种不一致。本着代码一致性的考虑，我希望这两个定义应该采用同样的词汇。

于是，我把 audit 和 review 同时放到了搜索引擎里查了一下。原来，audit 会有更官方的味道，更合适的翻译应该是审计，而 review 则有更多核查的意思，二者相比，review 更适合这里的场景。于是，章节的审核状态也统一使用了 review：

　　public enum ChapterReviewStatus {

　　    PENDING,
　　    APPROVED,
　　    REJECTED;

　　}

相比之下，这个坏味道是一个高级的坏味道，英语单词用得不准确。但这个问题确实是国内程序员不得不面对的一个尴尬的问题，我们的英语可能没有那么好，体会不到不同单词之间的差异。

很多人习惯的做法就是把中文的词扔到字典网站 (opens new window)，然后从诸多返回的结果中找一个自己看着顺眼的，而这也往往是很多问题出现的根源。这样写出来的程序看起来就像一个外国人在说中文，虽然你知道他在说的意思，但总觉得哪里怪怪的。

**在这种情况下，最好的解决方案还是建立起一个业务词汇表，千万不要臆想。**一般情况下，我们都可以去和业务方谈，共同确定一个词汇表，包含业务术语的中英文表达。这样在写代码的时候，你就可以参考这个词汇表给变量和函数命名。

英语单词的拼写错误

我再给你看一段曾经让我迷惑不已的代码：

　　public class QuerySort {

　　    private final SortBy sortBy;
　　    private final SortFiled sortFiled;

　　    ...

　　}

初看这段代码时，我还想表扬代码的作者，他知道把查询的排序做一个封装，比起那些把字符串传来传去的做法要好很多。

但仔细看一下代码，我脑子里就冒出了一系列问号。sortFiled 是啥？排序文件吗？为啥用的还是过去式？归档？

被这段代码搞晕的我只好打开提交历史，找出这段代码的作者，向他求教。

我：这个字段是啥意思？

同事：这是排序的字段啊。

我：排序的字段？

同事：你看，这个查询排序类有两个字段，一个是排序的方式，升序还是降序，另一个就是排序的字段。

我：字段这个单词是这么拼吗？

同事：不是吗？哦！是 field，拼错了，拼错了。

你看，是他把单词拼错了。

其实，偶尔的拼写错误是不可避免的，这就像我们写文章的时候，出现错别字也是难免的。之所以要在这个专栏中把拼写错误作为一种独立的坏味道，是因为在很多国内程序员写的程序中，见到的拼写错误比例是偏高的。

在这个故事里面，我都已经当面指出了问题，这个同事甚至都没有第一时间意识到自己的拼写是错误的，这其实说明了一种尴尬的现状：很多程序员对英语的感觉并没有那么强。

事实上，这个同事不止一次在代码里出现拼写错误了，一些拼写错误是很直白的，一眼就能看出来，所以，通常在代码评审的时候就能发现问题。这次的拼写错误刚好形成了另外一个有含义的单词，所以，我也被困住了。

对今天的程序员来说，工具已经很进步了，像 IntelliJ IDEA 这样的 IDE 甚至可以给你提示代码里有拼写错误（typo），不少支持插件的工具也都有自己的拼写检查插件，比如Visual Studio Code (opens new window) 就有自己的拼写检查插件。在这些工具的帮助之下，我们只要稍微注意一下，就可以修正很多这样低级的错误。

这一讲的内容几乎是完全针对国内程序员的。对于国外程序员来说，他们几乎不会犯这些错误。英语是程序员无论如何也绕不过去的一关，越是想成为优秀程序员，越要对英语有良好的感觉。当然，这里并不强求所有人的英语都能达到多好的程度，至少看到一些明显违反英语规则的代码，自己应该有能力看出来。

英语和程序设计语言其实是一样的，想用好，唯有多多练习。我自己的英语水平也算不上多好，但我读过很多技术文档，也看了很多开源的代码。之前因为参加开源项目和在外企工作的经历，也写过很多的英语邮件和文档，逐渐对程序中的英语有了感觉。