你真的会给变量命名吗？

有读者看到标题就开始敲键盘了，我知道，命名不就是不能用 abc、123 命名，名字要有意义嘛，这有什么好讲的？ 然而，即便懂得了名字要有意义，很多程序员依然无法逃离命名沼泽。

不精准的命名

什么叫精准？ 废话不多说，CR 一段代码：

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

看上去挺正常。 但我问你，这段代码在干嘛？你就需要调动全部注意力，去认真阅读这段代码，找出其中逻辑。经过阅读发现，这段代码做的就是把一个章节的翻译状态改成翻译中。

为什么你需要阅读这段代码细节，才知道这段代码在干嘛？

问题就在函数名，processChapter，这个函数确实是在处理章节，但这个名字太宽泛。如果说“将章节的翻译状态改成翻译中”叫做处理章节，那么：

• “将章节的翻译状态改成翻译完”
• “修改章节内容”

是不是也能叫处理章节？ 所以，如果各种场景都能叫处理章节，那么处理章节就是个宽泛名，没有错，但不精准！

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

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

或许这么说你的印象还是不深刻，看看下面这些词是不是经常出现在你的代码里：data、info、flag、process、handle、build、maintain、manage、modify 等等。这些名字都属于典型的过宽泛名字，当这些名字出现在你的代码里，多半是写代码的人当时没有想好用什么名字，就开始写代码了。

回到前面那段代码上，如果它不叫“处理章节”，那应该叫什么？

• 命名要能够描述出这段代码在做的事情 这段代码在做的事情就是“将章节修改为翻译中”。那是不是它就应该叫 changeChapterToTranlsating呢？ 相比于“处理章节”，changeChapterToTranlsating这个名字已经进了一步，然而，它也不算是一个好名字，因为它更多的是在描述这段代码在做的细节。 之所以要将一段代码封装起来，是我们不想知道那么多细节。如果把细节平铺开来，那本质上和直接阅读代码细节差别不大。
• 一个好的名字应该描述意图，而非细节 就这段代码而言， 我们为什么要把翻译状态修改成翻译中，这一定是有意图。我们把翻译状态修改成翻译中，是因为我们在这里开启了一个翻译的过程。所以，这段函数应该命名 startTranslation。

用技术术语命名

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

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

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

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

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

有什么更好的名字吗？我们需要一个更面向意图的名字。其实，我们在这段代码里真正要表达的是拿到了一堆书，所以，这个名字可以命名成 books。 List<Book> books = service.getBooks(); 这个名字其实更简单，但从表意的程度上来说，它却是一个更有效的名字。

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

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

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

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

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

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

• xxxMap这种命名表示映射关系，比如：书id与书的映射关系，不能命名为bookIdMap么？ Map 表示的是一个数据结构，而映射关系我会写成 Mapping

用业务语言写代码

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

编写可维护的代码要使用业务语言。怎么才知道自己的命名是否用的是业务语言呢？ 把这个词讲给产品经理，看他知不知道是怎么回事。

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

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

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

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

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

能够意识到自己的命名有问题，是程序员进阶的第一步。

 @GetMapping("getTotalSettlementInfoByYear")
 @ApiOperation("公司结算信息按年求和")
 public Result<List<RepMonthCompanyDTO>> getTotalSettlementInfoByYear(@RequestParam String year) {
 List<RepMonthCompanyDTO> list = repMonthCompanyService.getTotalSettlementInfoByYear(year);
 return new Result<List<RepMonthCompanyDTO>>().ok(list);
 }

名字长不是问题，问题是表达是否清晰，像repMonthCompanyService这个名字，是不太容易一眼看出来含义的。

另外，传给 service 的参数是一个字符串，这个从逻辑上是有问题的，没有进行参数的校验。后面的内容也会讲到，这个做法是一种缺乏封装的表现。

变量名是 list，按照这一讲的说法是用技术术语在命名。

再有，这个 URI 是
getTotalSettlementInfoByYear，这是不符合 REST 的命名规范的，比如，动词不应该出现在 URI 里，分词应该是“-”，byYear 实际上是一个过滤条件等等。

不管是日本人设计的 Ruby还是巴西人设计的 Lua，各种语法采用的全都是英语。所以，想要成为一个优秀的程序员，会用英语写代码是必要的。 你肯定听说过，国内有一些程序员用汉语拼音写代码，这就是一种典型坏味道。而且程序设计语言已支持 UTF-8，用汉语拼音写代码，还不如用汉字直接写代码。这场景太低级了，不过多讨论。

违反语法规则的命名

CR一段代码：

 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) {
   ...
 }

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

只要你懂得最基本的命名要求，知道最基本的英语规则，就完全能够发现这类坏味道。

不准确的英语词汇

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

 public enum ChapterAuditStatus {
     PENDING,
     APPROVED,
     REJECTED;
 }

有问题吗？看不出来，一点都不奇怪。如果你用审核作为关键字去字典网站上搜索，确实会得到 audit 这个词。所以，审核状态写成 AuditStatus 太正常了。

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

 public enum BookReviewStatus {
     PENDING,
     APPROVED,
     REJECTED;
 }

抛开前缀不看，同样是审核，一个用 audit，一个用 review。本着代码一致性，希望这两个定义采用同样词汇。

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

 public enum ChapterReviewStatus {
     PENDING,
     APPROVED,
     REJECTED;
 }

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

很多人就是把中文扔到 Google 翻译，然后从诸多返回的结果中找一个自己看着顺眼的，而这也往往是很多问题出现的根源。这样写出来的程序看起来就像一个不熟练的外国人在说中文，虽然你知道他在说的意思，但总觉得哪里怪怪的。

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

下面是一个词汇表的示例，从这个词汇表中你不难看出：

• 词汇表给出的都是业务术语，同时也给出了在特定业务场景下的含义
• 它也给出了相应的英文，省得你费劲心思去思考

遇到了一个词汇表中没有的术语，就找出这个术语相应的解释，然后补充到术语表。

用集体智慧，而非个体智慧。你一个人的英语可能没那么好，但一群人总会找出一个合适的说法。业务词汇表也是构建通用语言的一部分成果。

英语单词的拼写错误

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

 public class QuerySort {
     private final SortBy sortBy;
     private final SortFiled sortFiled;
     ...
 }

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

但仔细看，sortFiled 是啥？排序文件吗？为啥用的还是过去式？归档？ 找出这段代码的作者，向他求教，果然他把单词拼错了。

偶尔的拼写错误不可避免，国内的拼写错误比例是偏高的。

像 IntelliJ IDEA 这样的 IDE 甚至可以给你提示代码里有拼写错误（typo），只要稍微注意一下，就可以修正很多这样低级错误。

总结

两个典型的命名坏味道：

不精准的命名； 用技术术语命名。

命名是软件开发中两件难事之一（另一个难事是缓存失效），不好的命名本质上是增加我们的认知成本，同样也增加了后来人（包括我们自己）维护代码的成本。

• 好的命名要体现出这段代码在做的事情，而无需展开代码了解其中的细节
• 再进一步，好的命名要准确地体现意图，而不是实现细节
• 更高的要求是，用业务语言写代码

好的命名，是体现业务含义的命名。

几个英语使用不当造成的坏味道：

• 违反语法规则的命名
• 不准确的英语词汇
• 英语单词的拼写错误

还有一些常见的与语言相关的坏味道：

• 使用拼音进行命名
• 使用不恰当的单词简写（比如，多个单词的首字母，或者写单词其中的一部分）

如何从实践层面上更好地规避这些坏味道：

• 制定代码规范，比如，类名要用名词，函数名要用动词或动宾短语
• 要建立团队的词汇表
• 要经常进行CR

编写符合英语语法规则的代码。