改善代码质量的编程规范

改善代码质量的编程规范

Fri Sep 02

Author: 《设计模式之美》

根据《设计模式之美》中部分章节,整理记录下的改善代码质量的编程规范。内容主要分为三个部分:命名与注释、代码风格、编程技巧。文中代码示例使用了 Java 作为示例,但并不限于 Java,这些规范对于其他语言也是可以通用作为参考。

书写代码的质量非常依赖个人的开发经验,而下面总结出的这些规范,大部分简单明了,在阅读并掌握后,即使对于经验略少的开发者,在编写代码时对质量的提升也能够起到立竿见影的效果。

命名

1. 命名长度

实际开发中会遇到两种相对极端的命名方式,一种为了准确达意,命名尽可能的长,导致项目里类名、函数名都很长。另一种命名尽可能的短,能用缩写就用缩写,甚至字母。那么究竟那种方式更为合理?

我们要知道命名的原则是准确达意。理论上在足够表达其含义的基础上,命名越短越好。而在实际开发中,在遇到作用域较大的变量,为了减少可能产生的影响,更推荐用长的命名方式。

缩短命名的小建议,对于一些默认的、大家都比较熟悉的词可以使用缩写,可以让命名更短又不影响阅读理解。比如,sec 表示 second、str 表示 string、num 表示 number。

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

2. 利用上下文简化命名

public class User {
private String name; //not userName
private String password; //not userPassword
private String avatarUrl; //not userAvatarUrl
//...
}

类似情况下,借助上下文即可表意明确。同时也便于日后做一些抽象的操作。

3. 命名要可读、可搜索

命名可读指的是不要用一些特别生僻、难发音的英文单词或者不常见的缩写来命名。虽然我们不排斥一些独特的命名方式,但是起码得让大部分人看一眼就能知道怎么读。不影响沟通交流,这就算是一个比较好的命名。

命名可搜索指的是命名时最好能符合项目整体的命名习惯,便于在 IDE 中编写代码时联想补全以及搜索。比如大家都用“selectXXX”表示查询,你就不要用“queryXXX”;大家都用“insertXXX”表示插入一条数据,你就不要用“addXXX”。统一规约是很重要的,能较少很多不必要的麻烦。

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

接口有两种命名方式:一种是在接口中带前缀“l”;另一种是在接口的实现类中带后缀“lmpl”。对于抽象类的命名,也有两种方式,一种是带上前缀“abstract”,一种是不带前缀。这两种命名方式都可以,关键是要在项目中统一。

注释

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

1. 注释到底该写什么?

注释的目的就是让代码更容易看懂。只要符合这个要求的内容,你就可以将它写到注释里。

注释的内容主要包含这样三个方面:做什么、为什么、怎么做。

有些人认为,注释是要提供一些代码没有的额外信息,所以不要写“做什么、怎么做”,这两方面在代码中都可以体现出来,只需要写清楚“为什么”,表明代码的设计意图即可。

对于以上观点并不是特别认可,还是要分情况来处理,理由主要有以下 3 点:

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

注释太多和太少都有问题。

注释太多,有可能意味着代码写的不够可读,需要写很多注释来补充。除此之外,注释太多也会对代码本身的阅读起到干扰。而且,后期的维护成本也比较高,有时候代码改了,注释忘了同步修改,就会让代码阅读者更加迷惑。

如果代码中一行注释都没有,那只能说明这个程序员有点偷懒,我们要适当督促一下,让他注意添加一些必要的注释。

注释本身有一定的维护成本,所以并非越多越好,类和函数一定要写注释,而且要写的尽可能全面、详细,而函数内部的注释要相对少一些,一般都是靠好的命名、提炼函数、解释性变量、总结性注释来提高代码的可读性。

其他

关于注释,应该使用英文还是中文来书写呢?工作中还是要根据团队情况,交付要求等因素来决定。个人开发的话根据自身英文掌握情况,毕竟注释的目的是要让代码更容易看懂,英文足够熟练,那直接英文即可。如果不够熟练可以试着中文注释+英文注释,本着提升英文水平目的同时兼顾注释的可读性。

代码风格

1. 类、函数多大才合适?

总体上来讲,类或函数的代码行数不能太多,但也不能太少。类活函数的代码行数太多,一个类上千行,一个函数几百行,逻辑过于繁杂,阅读代码的时候,很容易就会看了后面忘了前面。相反,类或者函数的代码行数太少,在代码总量相同的情况下,被分隔成的类和函数就会相应增多,调用关系就会变得更复杂,阅读某个代码逻辑的时候,需要频繁地在 n 多类或者函数之间跳来跳去,阅读体验也不好。

要给出一个精确的量化值很难。比如做饭,对于放少许盐,即便是大厨也很难告诉你一个特别具体的量。

对于函数代码行数的最大限制,网上有一种说法,就是不要超过一个显示屏的垂直高度,让一个函数的代码完整的显示在 IDE 中。这个说法还是比较有道理的。因为超过一屏之后,阅读代码时为了串联前后的代码逻辑,就可能需要频繁的上下滚动屏幕,阅读体验不好喝不说,还容易出错。

对于类的代码行数的最大限制,这个就更难给出一个确切的值了。类当中往往包含了若干功能,高度大部分情况下都过超出一屏的显示范围。这里只能给一个间接的判断标准。那就是当一个类的代码读起来让你感觉吃力了,实现某个功能不知道改用哪个函数了,想用哪个函数翻半天都找不到,只用到一个小功能要引入整个类(类中包含很多无关此功能实现的函数)的时候,就说明类的行数过多了。

2. 一行代码多长合适?

不同编程语言、不同规范、不同团队,对此的限制可能都不同。不管这个限制是多少,总体上我们尽量遵循一个原则:一行代码的长度不超过 IDE 显示的宽度。不论是需要鼠标滚动才能查看完整代码还是 IDE 自动折行,都或多或少会不利于代码的阅读。当然,这个限制也不能太小,太小会导致很多稍长点的语句被折成两行,影响代码整洁以至于影响代码阅读。

3. 善用空行分割单元块

对于比较长的函数,如果逻辑上可以分为几个独立的代码块,在不方便将这些独立的代码块抽取成小函数的情况下,为了让逻辑更加清晰,除了前面提到的注释,我们还可以用空行来分割各个代码块。

除此之外,在类的成员变量与函数之间、静态成员变量与普通成员变量之间、各函数之间、甚至各成员变量之间,我们都可以通过添加空行的方式,让这些不同模块的代码之间,界限更加明确。类似写文章,善于应用空行,可以让代码的整体结构看起来更加清晰有条理。

4. 四格缩进还是两格缩进?

这个还是取决于个人喜好,保证项目内部能够统一就行了。

还有一个选择的标准,就是跟业内推荐的风格统一、跟著名开源项目统一。

需要强调的是,不管是用几格缩进,一定不要用 tab 键缩进。因为在不同的 IDE 下,tab 键的显示宽度有可能会不同,虽然可以通过 IDE 设置去配置,但是为了避免意外的麻烦,最好还是能够养成不要使用 tab 缩进的习惯。

5. 大括号是否要另起一行

将大括号放到跟上一条语句同一行,可以节省代码行数。但是将大括号另起新的一行的方式,左右括号可以垂直对齐,哪些代码属于哪一个代码块,更加一目了然。

6. 类中成员的排列顺序

在 Google Java 编程规范中,依赖类按照字母顺序从小到大排列。类中先写成员变量后写函数。成员变量之间或函数之间,先写静态成员变量或函数,后写普通变量或函数,并且按照作用域大小依次排列。

代码风格小结

以上所有代码风格都没有对错和优劣之分,只要能在团队、项目中统一即可,不过最好能跟业内推荐的风格、开源项目的代码风格相一致。

编程技巧

1. 把代码分割成更小的单元块

打不分人阅读代码的习惯都是先看整体再看细节。所以,我们要有模块化和抽象思维,善于将大块的复杂逻辑提炼成类或者函数,屏蔽掉细节,让阅读代码的人不至于迷失在细节中,这样能极大的提高代码的可读性。不过,只有代码逻辑比较复杂的时候,我们其实才建议提炼类或者函数。毕竟如果提炼出的函数只包含两三行代码,在阅读代码的时候,还得跳过去看一下,这样反倒增加了阅读成本。

2. 避免函数参数过多

个人觉得,函数包含 3、4 个参数的时候还是能接受的,大于等于 5 个的时候,就觉得参数有点过多了,会影响到代码的可读性,使用起来也不方便。针对参数过多的情况,一般有 2 中处理方法。

除此之外,如果函数是对外暴露的远程接口,将参数封装成对象,还可以提高接口的兼容性。在往接口中添加新的参数时,老的远程接口调用者有可能就不需要修改代码来兼容新的接口了。

3. 不要用函数参数来控制逻辑

不要在函数中使用布尔类型的标识参数来控制内容部逻辑,true 的时候走这块逻辑,false 的时候走另一块逻辑。这明显违背了单一职责原则和接口隔离原则。这种情况建议将其拆成两个函数,可读性上也要更好。

不过,如果函数是 private 私有函数,影响范围有限,或者拆分之后的两个函数经常同时被调用,我们可以酌情考虑保留标识参数。

4. 函数设计要职责单一

前面在说到单一职责原则的时候,针对的是类、模块这样的应用对象。实际上,对于函数的设计来说,更要满足单一职责原则。仙姑低于类和模块,函数的粒度比较小,代码行数少,所以在应用单一职责原则的时候,没有像应用到类或者模块那样模棱两可,能多单一就多单一。

5. 移除过深的嵌套层次

代码嵌套层次过深往往是因为 if-else、switch-case、for 循环过度嵌套导致的。个人建议,嵌套最好不超过两层,超过两层后就要思考一下是否可以减少嵌套。过深的嵌套本身理解起来就比较费劲,初次之外,嵌套过深很容易因为代码多次索引,导致嵌套内部的语句超过一行的长度而折行,影响代码的整洁。

解决嵌套过深的方法也比较成熟,有下面 4 种常见的思路:

初次之外,常用的还有通过使用多态来替代 if-else、switch-case 条件判断的方法。

6. 学会使用解释性变量

常用的解释性变量来提高代码的可读性的情况有下面 2 种。

统一代码规范

通过以上说到的命名、注释、代码风格、编程技巧这些知识点,可以发现大多数规范并没有一个准确的要求,只是建议或者推荐。最为重要的其实是,项目、团队乃至公司,应该制定统一的编码规范,并通过 Code Review 督促执行,这对提高代码质量有立竿见影的效果。