你真的会给变量命名吗

x33g5p2x  于2021-09-25 转载在 其他  
字(7.0k)|赞(0)|评价(0)|浏览(194)

有读者看到标题就开始敲键盘了,我知道,命名不就是不能用 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。

public void startTranslation(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);
}

用技术术语命名

我们再来看一段代码:

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

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

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

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

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

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

有什么更好的名字吗?我们需要一个更面向意图的名字。其实,我们在这段代码里真正要表达的是拿到了一堆书,所以,这个名字可以命名成 books。
List 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) {
  ...
}

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

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

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

用业务语言写代码

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

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

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

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

public void approveChapter(long chapterId, long userId) {
  ...
}

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

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

public void approveChapter(long chapterId, long reviewerUserId) {
  ...
}

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

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

@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

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

相关文章