Skip to content

31 | 理论五:让你最快速地改善代码质量的20条编程规范(上)

Tips

编码规范大部分都简单明了,在代码细节方面,能立竿见影地改善质量。

持续低层次、小规模重构,所依赖的基本上都是编码规范,这也是改善代码可读性的有效手段。

根据作者自己的开发经验,总结罗列了 20 条其个人觉得最好用的编码规范。掌握这 20 条编码规范,能最快速地改善代码质量。

编码规范共分为三个部分:

  1. 命名与注释(Naming and Comments)
  2. 代码风格(Code Style)
  3. 编程技巧(Coding Tips)

命名

大到项目名、模块名、包名、对外暴露的接口,小到类名、函数名、变量名、参数名,只要是做开发,就需要起名字。

命名的好坏,对于代码的可读性来说非常重要,甚至可以说是起决定性作用的。而命名能力也体现了一个程序员的基本编程素养。

对于影响范围比较大的命名,比如包名、接口、类名,我们一定要反复斟酌、推敲。实在想不到好名字的时候,可以去 GitHub 上用相关的关键词联想搜索一下,看看类似的代码是怎么命名的。

好的命名有什么标准?

1. 命名多长最合适?

Q: 很长的命名方式 vs 很短的命名方式,哪种更值得推荐呢?

A1: 尽管长的命名可以包含更多的信息,更能准确直观地表达意图,但是,如果函数、变量的命名很长,那由它们组成的语句就会很长。在代码列长度有限制的情况下,就会经常出现一条语句被分割成两行的情况,这其实会影响代码可读性

A2: 在足够表达其含义的情况下,命名越短越好。但是,大部分情况下,短的命名都没有长的命名更能达意。所以,很多书籍或者文章都不推荐在命名时使用缩写。

  • 对于一些默认的、大家都比较熟知的词,比较推荐用缩写。比如,sec 表示 second、str 表示 string、num 表示 number、doc 表示 document。

  • 对于作用域比较小的变量,我们可以使用相对短的命名,比如一些函数内的临时变量。相反,对于类名这种作用域比较大的,更推荐用长的命名方式。

总之,命名的一个原则就是以能准确达意为目标

对于代码的编写者来说,自己对代码的逻辑很清楚,总感觉用什么样的命名都可以达意,实际上,对于不熟悉你代码的同事来讲,可能就不这么认为了。所以,命名的时候,我们一定要学会换位思考,假设自己不熟悉这块代码,从代码阅读者的角度去考量命名是否足够直观。

2. 利用上下文简化命名

public class User {
  private String userName;
  private String userPassword;
  private String userAvatarUrl;
  //...
}

3. 命名要可读、可搜索

4. 如何命名接口和抽象类?

注释

命名很重要,注释跟命名同等重要。很多书籍认为,好的命名完全可以替代注释。如果需要注释,那说明命名不够好,需要在命名上下功夫,而不是添加注释。实际上,命名再好,毕竟有长度限制,不可能足够详尽,而这个时候,注释就是一个很好的补充。

1. 注释到底该写什么?

注释的目的就是让代码更容易看懂。只要符合这个要求的内容,就可以将它写到注释里。注释的内容主要包含这样三个方面:做什么、为什么、怎么做

2. 注释是不是越多越好?

重点总结

1. 关于命名

  • 命名的关键是能准确达意。对于不同作用域的命名,可以适当地选择不同的长度。作用域小的变量(比如临时变量),可以适当地选择短一些的命名方式。除此之外,命名中也可以使用一些耳熟能详的缩写。
  • 我们可以借助类的信息来简化属性、函数的命名,利用函数的信息来简化函数参数的命名。
  • 命名要可读、可搜索。不要使用生僻的、不好读的英文单词来命名。除此之外,命名要符合项目的统一规范,不要用些反直觉的命名。
  • 接口有两种命名方式:一种是在接口中带前缀“I”;另一种是在接口的实现类中带后缀“Impl”。对于抽象类的命名,也有两种方式,一种是带上前缀“Abstract”,一种是不带前缀。这两种命名方式都可以,关键是要在项目中统一。

2. 关于注释

  • 注释的目的就是让代码更容易看懂。只要符合这个要求的内容,就可以将它写到注释里。注释的内容主要包含这样三个方面:做什么、为什么、怎么做。对于一些复杂的类和接口,我们可能还需要写明“如何用”。
  • 注释本身有一定的维护成本,所以并非越多越好。类和函数一定要写注释,而且要写得尽可能全面、详细,而函数内部的注释要相对少一些,一般都是靠好的命名、提炼函数、解释性变量、总结性注释来提高代码可读性。