代码的艺术-Writing Code Like a Pianist

‍‍‍‍‍‍‍‍‍

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

【 工程师精神 】

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

【 提高代码可读性 】

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

二、客观角度

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

【 try/catch使用 】

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

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

try/catch块小有什么好处？

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

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

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

例如：

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

【 方法长度 】

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

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

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

简单重构后：

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

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

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

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

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

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

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

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

举个例子：

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

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

【 方法参数 】

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

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

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

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

【 减少缩进 】

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

来看看下面的代码：

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

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

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

【 单一职责 】

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

看下面的代码：

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

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

【 使用意义明确的命名 】

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

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

【 使用有意义的命名 】

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

【 类、方法命名规则 】

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

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

【 不要留无关内容 】

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

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

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

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

【 枚举 】

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

例如：

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

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

【 单元测试 】

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

三、结语

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

-    END    -