一天一点代码坏味道(1)

作为一个后端工程师,想必在职业生涯中都写过一些不好维护的代码。本文是我学习《代码之丑》的学习总结,今天第一天发车,先来看看在命名上的一些常犯的坏味道。

0 为何要品代码坏味道

Martin Flower在《重构》一书中给不好维护的这一类代码取了一个艺名:代码的坏味道,而这些坏味道一旦堆积多了,整个系统虽然还是可以平稳运行,但是就是让程序员不敢动,更别提重构了。

因为......

哎,都是打工人,谁容易啊?

1 不精准的命名

直接来看一段坏味道代码:

public void ProcessChapter(long chapterId)
{
    Chapter chapter = _repository.GetChapterById(chapterId);
    if (chapter == null)
    {
        throw new ArgumentException($"Unknown chapter [{chapterId}]");
    }

    chatper.TransactionState == TransactionState.TRANSLATING;
    _repository.UpdateChapter(chapter);
}

此段代码存在的问题:方法名ProcessChapter命名过于宽泛,不能精准描述意图,是代码难以理解的根源所在

同类型的词汇请各位看官自查,例如:data,info,flag,process,handle,build,maintain,manage,modify等等等,它们应该都出现在你我的项目代码中过。

重构方法:命名需要能够描述出这段代码在做的事情,根据代码的逻辑含义,调整其命名为 ChangeChapterToTranslating,是不是无论谁来接手这个方法的代码就都好理解了?

public void ChangeChapterToTranslating(long chapterId)
{
   ......
}

一个好的名字应该是描述意图,而非细节的。那么,我们再重构一下,结合具体的业务,将其命名改为 StartTranslation,即开始翻译,是不是就更能体现业务含义了?

public void StartTranslation(long chapterId)
{
   ......
}

2 用技术术语命名

这是一个我也经常犯的坏味道:

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

这个bookList的原因是因为它的类型是List,还有xxxDict,xxxMap等,它不费脑子,但它却只是一种基于实现细节的命名方式。

重构方法:使用面向意图的名字

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

又如,如果在业务代码中出现了Redis这类的中间件:

public Book GetByIsbn(string isbn)
{
    Book cachedBook = redisBookStore.Get(isbn);
    if (cachedBook != null)
    {
        return cachedBook;
    }

    Book book = service.GetByIsbn(isbn);
    redisBookStore.Put(isbn, book);
    return book;
}

通常来说,这里只是需要一个缓存,那么Redis也就只是这个缓存的一个具体实现,如果换为其他的NoSQL存储如Memcached呢?

因此,我们其实缺少了一个模型,在这里其实就是一个接口,假设这个接口如下:

public interface ICacheClient
{
    object Get(string key);
    void Put(string key, object value);
}

使用接口替代之后,我们就是面向接口编程了:

public Book GetByIsbn(string isbn)
{
    Book cachedBook = ICacheClient.Get(isbn);
    if (cachedBook != null)
    {
        return cachedBook;
    }

    Book book = service.GetByIsbn(isbn);
    ICacheClient.Put(isbn, book);
    return book;
}

技术人喜欢用技术名词命名,因为这是大家习惯的语言。但是,对于业务项目而言,需要尽可能将技术术语隔离开,因为业务语言才是最好的命名方式

DDD领域驱动设计方法就号召我们建立统一语言,这个统一语言是可以和业务部门的人员无障碍交流的语言,换句话说,也就是业务语言。另一方面来看,这就倒逼技术团队需要建立团队的业务词汇表,让团队成员达成统一共识,这也是要统一共识需要付出的额外成本,但是这个成本是有价值的。

编写可维护的代码之路

比如,我们经常会写下面的参数命名:

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

假设通过业务分析,这里的user其实是审核人,而我们为了方便就命名为userId了。那么,将其改为reviewerUserId是不是更加贴近业务?

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

在实际开发中,这样子的例子还有很多。

3 乱用英语来命名

作为一个受了多年义务教育与高等教育的我们来说,English一点也不陌生,但是就是始终感觉用不到位。

如果能用中文来命名,我们是不会到处查单词用英文来命名的,但是,用中文,没有B格啊,我放弃!

违反语法规则的命名

类是一个名字,表示一个对象。而方法名一般是一个动词或动宾短语,表示一个动作。但是,有时候,我们喜欢忽视这个规则。

public void CompletedTranslate(List<string> chapterIds)
{
    List<Chapter> chapters = _repository.GetByChapterIds(chapterIds);
    chapters.ForEach(chapter => chapter.TranslationState = TranslationState.TRANSLATED);
    _repository.SaveChapters(chapters);
}

CompletedTranslate 是个啥(四不像结构)?改为 CompleteTranslation 是不是好一点(动宾结构)?

public void CompleteTranslation(List<string> chapterIds)
{
    ......
}

又比如,一个方法名叫 ReTranslation(额,Translation好像是个名词吧),意为重新翻译,但作为方法名,应该选择动词,改为 ReTranslate 会更好(Translate是个动词,棒!)。

不准确的英语词汇

由于英文单词可以有多个含义,且在不同场景下含义也可以不同,这就难为我们中国人了。

比如,下面的一个枚举,想表达的是审核状态:

public enum ChapterAuditStatus
{
    PENDING,
    APPROVED,
    REJECTED
}

但是,Audit这个词虽然也有审核的含义,但是它更偏重于财务审计这块,而这里的业务是文稿的审核。

因此,改为Review可能会更加贴近一些:

public enum ChapterReviewStatus
{
    ......
}

从上也可以看出,技术团队建立一个统一的业务词汇表,很有必要!这是集体的智慧,而非个体的。一个人的英语可能不太好,但是一群人在一起,总有那么一个会找出合适的说法。

英语单词拼写错误

这个,我相信大家各自项目中都有不少拼错的案例,很多人查了单词之后,都还是拼错... 

但是,往往很多时候就是差了或者多了那么一个字母,就会让人懵逼了。

4 小结

本文总结了命名相关的两类坏味道,一是命名是否具有业务含义,二是命名是否符合英语语法。

最后,感谢郑晔老师的这门《代码之丑》课程,让我受益匪浅!我也诚心把它推荐给关注Edison博客的各位童鞋!

参考资料

郑晔,《代码之丑》(推荐订阅学习)

Martin Flower著,熊杰译,《重构:改善既有代码的设计》(推荐至少学习第三章)

👇扫码订阅《代码之丑》

 

posted @ 2021-02-04 21:50  EdisonZhou  阅读(232)  评论(0编辑  收藏  举报