代码优化(一):Java代码命名规范

原创
03/01 16:36
阅读数 41

编程中最难的事情 —— 命名!

怎么做好命名规范,这里结合了项目,分成四个等级。为以下:

  • 基础:命名风格
  • 第一级:精准命名,体现意图
  • 第二级:用业务语写代码
  • 第三级:编写符合英语语法规则的代码

基础:命名风格

每个公司都有自己的命名风格,比较有名的就是阿里开源的《阿里巴巴Java开发手册泰山版》,非常推荐去官网下载阅读。

像不要用中文、拼音、缩写这些很常见的就不说了;这里结合个人的项目,摘取了一些容易被忽视的规范,审视一下是否已经中招:

  1. 抽象类命名使用 Abstract 或 Base 开头;异常类命名使用 Exception 结尾;测试类 命名以它要测试的类的名称开始,以 Test 结尾

  2. 布尔类型的变量,不要加is前缀,否则部分框架会引起序列化错误

  3. 如果模块、接口、类、方法使用了设计模式,在命名时需体现出具体模式。(OrderFactory,LoginProxy,ResourceObserver)

  4. 接口的方法不要加修饰符(public也不要加)

  5. 各层命名规范

    a. Service/DAO 层方法命名规约

    • 获取单个对象的方法用 get 做前缀
    • 获取多个对象的方法用 list 做前缀,复数结尾,如:listObjects
    • 获取统计值的方法用 count 做前缀
    • 插入的方法用 save/insert 做前缀
    • 删除的方法用 remove/delete 做前缀
    • 修改的方法用 update 做前缀

    b. 领域模型命名规约

    • 数据对象:xxxDO,xxx 即为数据表名
    • 数据传输对象:xxxDTO,xxx 为业务领域相关的名称
    • 展示对象:xxxVO,xxx 一般为网页名称
    • POJO 是 DO/DTO/BO/VO 的统称,禁止命名成 xxxPOJO

第一级:精准命名,体现意图

通过前面命名风格,至少保证了代码符合了规范,但是并不一定是一个好的命名。好的命名首先要实现精准命名。

什么是非精准命名呢?举个反例:

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(处理章节): ”处理章节“是一个大的动作描述,可以是”开始处理章节“,”中止处理章节“,”添加章节内容“等等;具体做了什么,还是要看代码逻辑。
  • 改成changeChapterToTranlsating(将章节修改为翻译中):方法名描述了代码逻辑的细节。但是封装代码的重要原因就是 不想暴漏那么多细节,使用者只要知道这个方法是干嘛用的。
  • 改成startTranslation(开启翻译):正确命名,描述意图,非细节,是一个好的命名

业务层面的不精准,这种不精准比较难发现,属于高级坏味道:

//表示用户id为userId,但是不够精准,在这个场景下用户扮演的角色是审核人
public void approveChapter(long chapterId, long userId) {
	...
}

//审核人角色的用户id所以用reviewerUserId
public void approveChapter(long chapterId, long reviewerUserId) {
	...
}

第二级:用业务语写代码

什么叫做用业务语写代码,首先先了解一下它的对立面:用技术语写代码

List<Book> bookList = service.getBooks();
  • bookList,List是技术语,如果给到非技术人员,可能并不理解其含义
  • xxxList、xxxMap、xxxSet:种基于实现细节的命名方式,如果修改返回类型,变量名是不一定会修改
  • 好的命名应该是业务语,如:books

技术名词的出现,代表它缺少一个应有的模型,如redis

//命名出现了redis
Book cachedBook = redisBookStore.get(isbn);
//redis  改为 cache,好一点,但是cache也是技术术语
Book cachedBook = cache.get(isbn);

spring较好的处理方式,添加Annotation

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

以上讨论的是基于业务类的项目,尽可能使用业务语言;但是对于技术类的项目,技术名称就是它的业务语言,这就另当别论了。

第三级:编写符合英语语法规则的代码

错别字满天飞的文章,很难让人相信是一篇好文章。阿里开发手册也说明了:

  • 不要用拼音写代码
  • 不要用单词首字母,或者一部分
  • 不要用无意义的字母做变量

...

这里讨论的是 命名的语法结构 和 准确用词:

  1. 命名的语法结构

    • 类名应该为名词,表示一个对象。
    • 方法名 为 动词动宾,表示一个动作

    举两个反例:

    • completedTranslate(完成翻译)不是有效的动宾,要把“完成”译为 complete,“翻译”用成它的名词形式 translation,所以应改为completeTranslation(动词+名词)
    • retranslation(重新翻译)不是动词,改为retranslate
  2. 准确用词

    首先就是拼写错误,可以借助IDE的typo拼写错误检查。

    再者是用词错误:例如 "审核" ,如果直接翻译,可能 得到 audit,review两个词。那到底用那个词呢?audit更有官方味道,更适合审计。review更符合审核的场景。

    要解决这个问题,建议建立团队的业务词汇表,规定常用词汇。如下:

    名称

    英文

    说明

    作品

    Book

    作者创作的作品

    章节

    Chapter

    作品的一部分

    审核

    review

    审核方对作品内容进行查看的过程

    审核通过

    approve

    审核方对作品内容予以通过

    审核未通过

    reject

    审核方对作品内容不予通过

参考资料:

展开阅读全文
打赏
0
0 收藏
分享
加载中
更多评论
打赏
0 评论
0 收藏
0
分享
返回顶部
顶部