代码的艺术-Writing Code Like a Pianist

时间:2024-01-22 16:54:43

前言

如何评定一个系统的质量?什么样的系统或者软件可以称之为高质量?可以从三个角度来看,一是架构设计,例如技术选型、分布式系统中的数据一致性考虑等,二是项目管理,无论是敏捷开发还是瀑布式开发,都应当对技术负债进行清理,对代码进行重构等,最后离不开的是代码质量,代码质量的高低直接影响系统的可维护性和可扩展性。好比一辆汽车,内饰高级,外观漂亮,但是底盘不行,动力孱弱,也难以称得上是一辆好车。本文将从主观和客观的角度,和大家探讨一下,作为程序员,应该如何写出整洁高质量的代码。

主观角度

工程师精神

点开京ME头像可以看到,咱们内部的title是“xx开发工程师”,而不是“xx代码编写员”,这个师可以理解为大师的师(master),大师级程序员把系统当作故事来讲,而不是当作程序来写。作为开发者,应该对自己写下的代码负责,当在一个类上@author冠名的时候,应当有一种成就感,在未来的某一天,可能一年,两年甚至五年之后,其他同事读到这段代码,会由衷的发出感叹“牛B”,而不是吐槽“写的什么玩意”,Doug Lea写的并发包,时隔多年,他的大名依然如雷贯耳。

提高代码可读性

首先应当达成共识的是,代码是写给人看的,给机器运行那只是基础,优秀的代码,不需要过多的注释,代码本身就是注释。可读性指的是,其他开发人员能够迅速理解代码的意图和功能,简洁的代码更易于理解、测试和维护。其次,避免重复,代码重复是软件中一切邪恶的根源,许多原则和设计模式都是为了消除重复而创建。

客观角度

接下来从客观角度,例举日常代码评审中的常见问题,给大家作一些参考。

try/catch使用

1\. try/catch块应该尽量的小,只针对无法预料的情况进行try/catch,可以预见的异常情况应该在try之前被校验住。

无法预料的情况:远程调用,IO读写,第三方API等。 可以预见的情况:某个参数为空,某个列表无元素等。

代码的艺术-Writing Code Like a Pianist_单一职责原则

try/catch块小有什么好处?

•代码整洁,可以减少其他代码的缩进

•异常控制精细,可以对具体异常进行具体的提示、UMP报警、日志输出或者错误码返回

2\. 如果确实需要对整段方法进行tryCatch,不如新写一个方法,将业务逻辑处理和异常处理区分开来。

例如:

代码的艺术-Writing Code Like a Pianist_嵌套_02

try/catch代码块中的内容多,说明对代码掌控能力不够好 如果存在try,那么尽量保证try在第一行,并且在catch/finally后不该有其他内容

方法长度

方法行数应该尽可能的短,越短越好。能够让读者点进来的一瞬间就明白这个方法做了什么事情。举个例子:

代码的艺术-Writing Code Like a Pianist_数据_03

这是一个查询价格的方法,这个方法长度截图已经一页截不下了。如果要想搞明白这个方法做了什么事,凭借方法体中的注释是没法轻易梳理清楚。

只需要做简单的一些处理的包装,这个方法就能变得通俗易懂,而且并不用写一行注释。

简单重构后:

代码的艺术-Writing Code Like a Pianist_嵌套_04

代码的艺术-Writing Code Like a Pianist_单一职责原则_05

代码的艺术-Writing Code Like a Pianist_嵌套_06

从上面的代码上看,第一段将价格查询的代码分成了两个部分,首先解析查询的审批状态,然后根据审批状态分别查询价格。第二段将价格查询分成了两个部分,一个是查询审批中的价格,另一个是查询审批通过的价格,最后将二者组合起来返回。第三段是截了审批中价格查询的代码,显而易见地,查询审批中价格有两种模式,百分比模式和底价模式,查询到结果后,组合返回即得到商品的渠道价。

对比一下不难看出,原代码块篇幅过长,嵌套较深(for循环嵌套if再嵌套if),导致可读性下降。如果我想改动某块的代码,都需要深思熟虑。但是在拆分之后,就可以快速定位到目标代码块,并且不用担心对其他方法产生影响,另外,对其进行单元测试也会比较方便编写测试用例。

禁止在方法内部修改入参数据

从系统概念上来看,一般可以将系统分为两类,一类是给一个输入,得到一个输出,这类称之为响应式,另一类是给一个输入,但是没有输出,这类被认为是命令式。同理,对于方法而言,响应式方法即给定一个入参,得到一个出参,比较常见的比如模型转换、数据查询等,命令式方法有发送消息、run一个线程。

但是无论怎么变化,这些都有一个共同点,他们不会去修改入参的数据

  1. 引起意外的副作用:如果方法修改了传入的参数,而调用者依赖于原始的参数值,那么调用者可能会在不知情的情况下受到影响。这可能导致程序的行为变得难以预测,增加代码的复杂性和错误的可能性。

2.破坏数据的一致性:如果多个方法共享同一个对象作为参数,并且这些方法都可以修改该对象,这些方法可能会相互干扰,导致数据状态变得混乱和不可预测。

3.可能增加代码的维护难度:当方法修改传入的参数时,调用该方法的代码可能需要依赖于这种修改行为。这样会增加代码的耦合性,使得代码更难以理解、维护和重用。当需要对方法进行修改时,可能需要同时修改调用该方法的所有地方,增加了代码的维护成本。

举个例子:

代码的艺术-Writing Code Like a Pianist_数据_07

这里调用了3个set方法,但是谁能一眼看出来,它把值set到哪个object里了?还得挨个点进去看看具体实现,才知道在哪里赋值了。

如果确实需要修改参数的值,可以创建一个新的对象来存储修改后的结果,并将其返回给调用者。这样可以保持代码的清晰性、可维护性和可测试性,减少意外的副作用和数据一致性问题。

方法参数

方法的参数也是越少越好,最理想的参数是无参,其次是单参,应该尽量避免三个或者三个以上的参数

继续上面的代码,最后一行“设置渠道类型”,set方法里有两个入参,完全可以将其赋值对象提取出来,减少一个入参,如下:

代码的艺术-Writing Code Like a Pianist_单一职责原则_08

如果方法的处理逻辑,只依赖于某一局部变量object的数据,那么完全可以将这个方法放在对象内部,进一步减少方法参数,提高代码复用性,例如:

代码的艺术-Writing Code Like a Pianist_数据_09

这样来看,就成功将两个入参的方法,缩减成了无参方法,和原始代码相比,原始代码方法的作用域仅限于类内部,而最终的无参方法,只需要拿到目标对象实例即可在任何地方调用,还能减少重复代码的编写。

减少缩进

代码中出现大量的缩进显然是影响阅读的,在可能的情况下,我们应该尽可能的减少代码中的缩进和层次。好的代码读起来应该是和报纸一样,排版整齐优雅,而不是爬楼梯。

来看看下面的代码:

代码的艺术-Writing Code Like a Pianist_数据_10

代码中出现两层if嵌套,首先我们可以对第一层if嵌套做一个简化,简单将if的判断条件做一个反转得到下面代码:

代码的艺术-Writing Code Like a Pianist_单一职责原则_11

这样就减少了一层缩进,然后再将变量和参数进行一些微调:

代码的艺术-Writing Code Like a Pianist_嵌套_12

这样,和之前的代码比起来,是不是可读性提高了?

单一职责

在面向对象编程中,"单一职责原则"(Single Responsibility Principle,SRP)是指一个类或模块应该只有一个引起它变化的原因,即一个类或模块应该只有一个主要责任或目标。通过细化功能和职责,可以提高代码的可维护性、复用性和可扩展性。

看下面的代码:

代码的艺术-Writing Code Like a Pianist_数据_13

这个方法是从声明上来看,是用于保存任务数据,但是实际上如果入参中的某些数据不为空(实际上看这个方法的实现也很难一眼看出来具体是哪些数据),会进行更新update操作。这种写法不仅容易让读者感到困惑,也会降低代码的可扩展性。

Q:AtomicInteger的compareAndSet方法违反了单一职责吗? A:并不违反单一职责原则。compareAndSet 方法是 AtomicInteger 类提供的一种原子操作,用于比较当前值与给定期望值是否相等,如果相等则将当前值设置为新值。这个方法的职责是实现原子性的比较和设置操作,确保在多线程环境下的线程安全性。compareAndSet 方法作为其中的一种操作,是为了满足特定的需求而设计的,它并不违反单一职责原则。单一职责原则要求一个类或模块只有一个主要责任,而 AtomicInteger 类的主要责任是提供原子整数操作,compareAndSet 方法是其中的一部分,属于该类主要责任的一部分。因此,compareAndSet 方法并不违反单一职责原则。

使用意义明确的命名

下面的代码,checkParam的返回值是布尔值,但是作为读者,我不知道是应该check通过了返回True,还是check失败的情况下返回True。

代码的艺术-Writing Code Like a Pianist_嵌套_14

一般而言,check作为开头的方法名称,没有返回值,对于check不通过的情况以异常的形式抛出。返回布尔值的方法通常以is作为起始,换种写法看看是不是会好读很多?

代码的艺术-Writing Code Like a Pianist_嵌套_15

使用有意义的命名

这里比较典型的是flow编排文件里的条件判断节点,使用0,1这类没有意义的数字,很难一眼看出来说了什么,需要挨个点进去看逻辑,才能梳理明白,改成有意义的命名,便于理解。

代码的艺术-Writing Code Like a Pianist_单一职责原则_16

类、方法命名规则

类名使用名词或者名词短语 方法命名使用动词或者动名词结构

这个比较好理解,暂不举例了。

不要留无关内容

在发起MR之前,检查一遍代码里有没有“被注释掉的代码”以及TODO。

对于注释掉的代码而言,如果后续有其他开发人员介入,他们会觉得非常困惑,这两行代码为什么要注释掉?它们重要吗?它们放在那里,是因为在未来的某一天需要用?还是说只是当时忘记删除了?还是说为了给未来修改做提示?这些顾虑可能让其他开发人员也不敢动手清理这些被注释的代码,进而造成这些代码被永久的保留下来,形成“幽灵代码”。

对于TODO来说,建议在写todo的时候,要求在后面跟上自己的ERP,谁来解决,怎么解决,deadLine是什么时候。因为在大多数情况下,Later equals never。久而久之,连自己都忘了这个todo,忘了当时为啥写这个todo,应该怎么处理,给系统埋下隐患。

代码的艺术-Writing Code Like a Pianist_嵌套_17

如上,当年写下这个TODO的同事已经离职了,现在只有上帝才知道todo什么东西。

枚举

养成良好的习惯,在用枚举定义的变量,拉一条引用指向枚举,方便其他开发人员阅读。

例如:

代码的艺术-Writing Code Like a Pianist_数据_18

这是一个可穷举的变量(因为状态是有限的),但是读者不知道具体都有哪些状态。这里其实是有一个枚举关联上来的.

代码的艺术-Writing Code Like a Pianist_嵌套_19

为了方便阅读,可以在变量定义的地方,使用javaDoc的@see/@link方式,说明这个变量的枚举范围。

代码的艺术-Writing Code Like a Pianist_单一职责原则_20

单元测试

单测的重要性不言而喻,这里先挖个坑,后续单开一篇写。

结语

写在最后,给大家推荐一本经典书籍《代码整洁之道》,实际上该书的出版时间较早,书中的某些知识或许有些过时,但是前面几章内容仍然值得一读。整洁的代码需要团队的共同努力,团队成员应该遵循一致的编码风格和标准,进行代码审查和知识分享,共同维护和改进代码质量。它不仅仅是一种编码风格,更是一种思维方式和价值观。优雅的代码,就像是艺术品,正如标题所言,应当像一名钢琴家一样编写代码。

作者:京东零售 谭磊

来源:京东云开发者社区 转载请注明来源