如何写出优雅的代码

前言

整洁的代码至少要保证两点： 1、整洁美观，能让人看了会心一笑； 2、运行效率、性能最优！ 代码整洁之道，大道至简也！最终要达到减少重复代码，提高表达力，构建抽象层、中间件！ 普通的工程师堆砌代码，优秀的工程师优雅代码，卓越的工程师简化代码。如何写出优雅整洁易懂的代码是一门学问，也是软件工程实践里重要的一环。 好代码一定是整洁的，整洁是好代码的必要条件。整洁的代码一定是高内聚低耦合的，也一定是可读性强、易维护的。

注释

• 不要给不好的名字加注释，一个好的名字比好的注释更重要
• 不要“拐杖注释”，好代码 > 坏代码 + 好注释
• 在文件/类级别使用全局注释来解释所有部分如何工作
• 一定要给常量加注释
• 团队统一定义标记
• TODO 待处理的问题
• FIXME 已知有问题的代码
• HACK 不得不采用的粗糙的解决方案
• 在注释中用精心挑选的输入输出例子进行说明
• 注释应该声明代码的高层次意图，而非明显的细节
• 不要在代码中加入代码的著作信息，git 可以干的事情不要交给代码
• 源代码中的 html 注释是一种厌物, 增加阅读难度
• 注释一定要描述离它最近的代码
• 注释一定要与代码对应
• 公共 api 需要添加注释，其它代码谨慎使用注释
• 典型的烂注释
• 不恰当的信息
• 废弃的注释
• 冗余注释
• 糟糕的注释
• 注释掉的代码
• 唯一真正好的注释是你想办法不去写的注释
• 不要有循规式注释，比如 setter/getter 注释
• 不要添加日志式注释，比如修改时间等信息（git 可以做的事情）
• 注释一定是表达代码之外的东西，代码可以包含的内容，注释中一定不要出现
• 如果有必要注释，请注释意图（why），而不要去注释实现（how)，大家都会看代码
• 适当添加警示注释

命名

• 尽可能使用标准命名方法，比如设计模式，通用学术名词等
• 命名要找更有表现力的词
• 使用更专业的词，比如不用 get 而使用 fetch 或者 download
• 避免空泛的名字，像 tmp
• 使用具体的名字来细致的描述事物
• 给变量名带上重要的细节，比如加上单位 ms 等
• 为作用域大的名字采用更长的名字，作用域小的使用短名字
• 变量类型为布尔值表达加上 is，has，can，should 这样的词会更明确
• 变量名称长短应该与其作用域对应
• 别害怕长名称，长而具有描述性的名称比短而令人费解的名称好
• 函数名称应该说明副作用，名称应该表达函数，变量或类的一切信息，请不要掩盖副作用，比如 CreateAndReturnXXX

方法

• 函数不应该有 100 行那么长，20 行封顶最好
• if else while 等控制语句其中代码块应该只有一行，也就是一个函数调用语句
• 函数的锁进层次不应该多于两层
• 一个函数只做一件事，一个函数不应该能抽象出另外一个函数
• 某个公共函数调用的私有函数紧随其后
• 最理想的参数是零参数，最长不要超过三个入参，尽量不要输出参数
• 如果函数传入三个及以上参数最好将其抽象为类
• 标识参数十分丑陋，向函数传入布尔值用于区分不同业务的做法很丑陋，应该拆分为多个函数
• 别返回 null 值，抛出异常或者返回特殊对象，尽量避免 NPE
• 别传入 null 值

异常与错误

• 抽离 try catch 包含的代码块，其中代码块抽象为一个函数
• 抛出的每个异常，都应当提供足够的环境说明，已便判断错误的来源与处所
• 不要将系统错误归咎于偶然事件

并发

• 分离并发相关代码与其它代码
• 严格限制对可能被共享的数据的访问
• 避免使用一个共享对象的多个同步方法
• 保持同步区域微小，尽可能少设计临界区

单元测试

• 不要怕单元测试的方法名字太长或者繁琐，测试函数的名称就像注释
• 不要追求太高的测试覆盖率，测试代码前面 90%通常比后面 10%花的时间少
• 使用最简单的并且能够完整运用代码的测试输入
• 给测试函数取一个完整性的描述性名字，比如 Test
• 测试代码与生产代码一样重要
• 如果测试代码不能保证整洁，你就会很快失去他们
• 每个测试一个断言，单个测试中断言数量应该最小化也就是一个断言

FIRST 原则

• 快速 Fast
• 独立 Independent 测试应该相互独立
• 可重复 Repeatable 测试应当在任何环境中重复通过
• 自足验证 Self-Validating 测试应该有布尔值输出
• 及时 Timely 最好的方式是 TDD

代码结构

• 代码行长度控制在 100-120 个字符
• 可能用大多数为 200 行，最长 500 行的单个文件构造出色的系统
• 关系密切的代码应该相互靠近
• 变量声明应该靠近其使用位置
• 若某个函数调用了另外一个，应该把他们放在一起，而且调用者应该放在被调用者上面
• 自上向下展示函数调用依赖顺序
• 应该把解释条件意图的函数抽离出来，尽可能将条件表达为肯定形式
• 不要继承常量，比如接口中定义常量，不要使用继承欺骗编程语言的作用范围规则
• 模块不应了解它所操作对象的内部情况
• DTO（Data Transfer Objects）是一个只有公共变量没有函数的类
• 对象暴露行为，隐藏数据
• 不要使用“尤达表示法” 如 if(null == obj)，现代编译器对 if(obj = null)这样的代码会给出警告
• 一般情况使用 if else，简单语句使用三目运算符
• 通常来讲提早返回可以减少嵌套并让代码整洁

设计

• 类应该足够短小
• 类应该满足单一权责原则（SRP），类和模块只有一个修改理由
• 类应该只有少量的实体变量
• 类应该遵循依赖倒置原则 DIP（Dependency Inversion Principle），类应该依赖于抽象而不是依赖于具体细节
• 类中的方法越少越好，函数知道的变量越少越好，类拥有的实体变量越少越好
• 通过减少变量的数量和让他们尽量“轻量级”来让代码更有可读性
• 减少变量
• 缩小变量的作用域
• 只写一次的变量更好，如常量
• 最好读的代码就是没有代码
• 从项目中消除不必要的功能，不要过度设计
• 从新考虑需求，解决版本最简单的问题，只要能完成工作就行
• 经常性地通读标准库的整个 API，保持对他们的熟悉程度

简单设计

• 运行所有测试
• 不可重复
• 表达了程序员的意图
• 尽可能减少类和方法的数量
• 以上规则按重要程度排列
• 无论是设计系统或者单独模块，别忘了使用大概可工作的最简单方案
• 整洁的代码只提供一种而非多种做一件事的途径，他只有尽量少的依赖。明确定义并提供尽量少的 API
• 减少重复代码，提高表达力，提早构建，简单抽象

小结

作为代码整洁之道系列的第一篇，本文从注释、命名、方法，单元测试，并发等视角简单给出了一些最佳实践，下文我们会展开来从每个方面介绍更多的实践事例。相信每一个优秀的工程师都有一颗追求卓越代码的心，在代码整洁工程实践上你有哪些好的建议？数百人协作开发的代码如何保证代码整洁一致性？欢迎大家来讨论。

高内聚低耦合

高内聚低耦合几乎是每个程序员员都会挂在嘴边的，但这个词太过于宽泛，太过于正确，所以聪明的编程人员们提出了若干面向对象设计原则来衡量代码的优劣：

• 开闭原则 OCP (The Open-Close Principle)
• 单一职责原则 SRP (Single Responsibility Principle)
• 依赖倒置原则 DIP (Dependence Inversion Principle)
• 最少知识原则 LKP (Least Knowledge Principle)) / 迪米特法则 (Law Of Demeter)
• 里氏替换原则 LSP (Liskov Substitution Principle)
• 接口隔离原则 ISP (Interface Segregation Principle)
• 组合/聚合复用原则 CARP (Composite/Aggregate Reuse Principle)

这些原则想必大家都很熟悉了，是我们编写代码时的指导方针，按照这些原则开发的代码具有高内聚低耦合的特性。换句话说，我们可以用这些原则来衡量代码的优劣。

但这些原则并不是死板的教条，我们也经常会因为其他的权衡（例如可读性、复杂度等）违背或者放弃一些原则。比如子类拥有特性的方法时，我们很可能打破里氏替换原则。再比如，单一职责原则跟接口隔离原则有时候是冲突的，我们通常会舍弃接口隔离原则，保持单一职责。只要打破原则的理由足够充分，也并不见得是坏的代码。

可读性

代码只要具有了高内聚和低耦合就足够好了吗？并不见得，我认为代码还必须是易读的。好的代码无论是风格、结构还是设计上都应该是可读性很强的。可以从以下几个方面考虑整洁代码，提高可读性。

命名

大到项目名、包名、类名，小到方法名、变量名、参数名，甚至是一个临时变量的名称，其命名都是很严肃的事，好的名字需要斟酌。

► 名副其实

好的名称一定是名副其实的，不需要注释解释即可明白其含义的。

/**
 * 创建后的天数
**/
int d;
int daysSinceCreation;

后者比前者的命名要好很多，阅读者一下子就明白了变量的意思。

► 容易区分

我们很容易就会写下非常相近的方法名，仅从名称无法区分两者到底有啥区别（eg. getAccount()与getAccountInfo()），这样在调用时也很难抉择要用哪个，需要去看实现的代码才能确定。

► 可读的

名称一定是可读的，易读的，最好不要用自创的缩写，或者中英文混写。

► 足够短

名称当然不是越长越好，应该在足够表达其含义的情况下越短越好。

格式

良好的代码格式也是提高可读性非常重要的一环，分为垂直格式和水平格式。

► 垂直格式

通常一行只写一个表达式或者子句。一组代码代表一个完整的思路，不同组的代码中间用空行间隔。

public class Demo {
    @Resource
    private List<Handler> handlerList;
    private Map<TypeEnum, Handler> handlerMap = new ConcurrentHashMap<>();
    @PostConstruct
    private void init() {
        if (!CollectionUtils.isEmpty(handlerList)) {
            for (Handler handler : handlerList) {
                handlerMap.put(handler.getType(), handler);
            }
        }
    }
    publicResult<Map<String, Object>> query(Long id, TypeEnum typeEnum) {
        Handler handler = handlerMap.get(typeEnum);
        if (null == handler) {
            return Result.returnFailed(ErrorCode.CAN_NOT_HANDLE);
        }
        return handler.query(id);
    }
}

如果去掉了空行，可读性大大降低。

  public class Demo {
      @Resource
      private List<Handler> handlerList;
      private Map<TypeEnum, Handler> handlerMap = new ConcurrentHashMap<>();
      @PostConstruct
      private void init() {
          if (!CollectionUtils.isEmpty(handlerList)) {
              for (Handler handler : handlerList) {
                  handlerMap.put(handler.getType(), handler); } } }
      public Result<Map<String, Object>> query(Long id, TypeEnum typeEnum) {
          Handler handler = handlerMap.get(typeEnum);
          if (null == handler) {
              return Result.returnFailed(ErrorCode.CAN_NOT_HANDLE);
          }
          return handler.query(id); }
  }

类静态变量、实体变量应定义在类的顶部。类内方法定义顺序依次是：公有方法或保护方法 > 私有方法 > getter/setter 方法。

► 水平格式

要有适当的缩进和空格。

► 团队统一

通常，同一个团队的风格尽量保持一致。集团对于 Java 开发进行了非常详细的规范。（可点击下方阅读原文，了解更多内容）

类与函数

► 类和函数应短小，更短小

类和函数都不应该过长（集团要求函数长度最多不能超过 80 行），过长的函数可读性一定差，往往也包含了大量重复的代码。

► 函数只做一件事（同一层次的事）

同一个函数的每条执行语句应该是统一层次的抽象。例如，我们经常会写一个函数需要给某个 DTO 赋值，然后再调用接口，接着返回结果。那么这个函数应该包含三步：DTO 赋值，调用接口，处理结果。如果函数中还包含了 DTO 赋值的具体操作，那么说明此函数的执行语句并不是在同一层次的抽象。

► 参数越少越好

参数越多的函数，调用时越麻烦。尽量保持参数数量足够少，最好是没有。

注释

► 别给糟糕的代码加注释，重构他

注释不能美化糟糕的代码。当企图使用注释前，先考虑是否可以通过调整结构，命名等操作，消除写注释的必要，往往这样做之后注释就多余了。

► 好的注释提供信息、表达意图、阐释、警告

我们经常遇到这样的情况：注释写的代码执行逻辑与实际代码的逻辑并不符合。大多数时候都是因为代码变化了，而注释并没有跟进变化。所以，注释最好提供一些代码没有的额外信息，展示自己的设计意图，而不是写具体如何实现。

► 删除掉注释的代码

git 等版本控制已经帮我们记录了代码的变更历史，没必要继续留着过时的代码，注释的代码也会对阅读等造成干扰。

错误处理

► 错误处理很重要，但他不能搞乱代码逻辑

错误处理应该集中在同一层处理，并且错误处理的函数最好不包含其他的业务逻辑代码，只需要处理错误信息即可。

► 抛出异常时提供足够多的环境和说明，方便排查问题

异常抛出时最好将执行的类名，关键数据，环境信息等均抛出，此时自定义的异常类就派上用场了，通过统一的一层处理异常，可以方便快速地定位到问题。

► 特例模型可消除异常控制或者 null 判断

大多数的异常都是来源于 NPE，有时候这个可以通过 Null Object 来消除掉。

► 尽量不要返回 null ，不要传 null 参数

不返回 null 和不传 null 也是为了尽量降低 NPE 的可能性。

如何判断不是好的代码

讨论了好代码的必要条件，我们再来看看好代码的否定条件：什么不是好的代码。Kent Beck 使用味道来形容重构的时机，我认为当代码有坏味道的时候，也代表了其并不是好的代码。

代码的坏味道

► 重复

重复可能是软件中一切邪恶的根源。—— Robert C.Martin

Martin Fowler 也认为坏味道中首当其冲的就是重复代码。 很多时候，当我们消除了重复代码之后，发现代码就已经比原来整洁多了。

► 函数过长、类过大、参数过长

过长的函数解释能力、共享能力、选择能力都较差，也不易维护。

过大的类代表了类做了很多事情，也常常有过多的重复代码。

参数过长，不易理解，调用时也容易出错。

► 发散式变化、霰弹式修改、依恋情结

如果一个类不是单一职责的，则不同的变化可能都需要修改这个类，说明存在发散式变化，应考虑将不同的变化分离开。

如果某个变化需要修改多个类的方法，则说明存在霰弹式修改，应考虑将这些需要修改的方法放入同一个类。

如果函数对于某个类的兴趣高于了自己所处的类，说明存在依恋情结，应考虑将函数转移到他应有的类中。

► 数据泥团

有时候会发现三四个相同的字段，在多个类和函数中均出现，这时候说明有必要给这一组字段建立一个类，将其封装起来。

► 过多的 if...else 或者使用 switch

过多的 if...else 或者 switch ，都应该考虑用多态来替换掉。甚至有些人认为除个别情况外，代码中就不应该存在 if...else 。