为了降低与优化代码维护的成本，以及减少线上故障发生的次数，我们制定了一系列的规则与框架，甚至这些框架中建议我们写出降低程序运行效率的代码

为了写出简单易懂可维护的代码，为了成为更好的程序员，我们应该遵守以下的规则

命名

我们需要给变量、函数、参数、类与包命名，同时需要满足以下要求

• 名副其实：不要使用 d、o、a 什么的，使用更加多的字符尽可能描述被描述者的作用
• 避免误导：命名时避免使用与本意相悖的词。使用 accountList 来指一组账号，除非它真的是 List 类型。如果容纳账号的容器是 Set，那就会引起错误的判断
• 魔法值使用静态常量：单字母名称和数字常量有个问题，很难在一大篇文字中找出。找 MAX_CLASS_PER_STUDENT 很容易，想找数字7就很麻烦。单字母名称仅用于短方法中的本地变量。名称应与其作用域相对应，比如在一个类中经常使用的，就可以通过大写字母的方式来表示
• 避免使用编码：反例：变量名加入成员前缀 m_name 表示接口时加上 I 字母 接口名：IShapeFactory
• 避免思维映射：在循环体中通过变量来判断条件时，使用 i,j 或者 k 就比其他字母好。千万别用小写字母 l 和大写字母 O
• 类名应该是名词或者名词短语，而方法名则应当是动词或者动词短语
• 给每一个抽象概念选一个词，并且一以贯之

函数

• 函数越短小越好，比如 if/else/while 语句的代码块应该只有一行，该行应该是一个函数调用语句。函数的缩进层级不应该多于一层或两层
• 一个函数只做一件事
• 使用描述性的名称，函数越短小、功能越集中，就越便于取个好名字
• 关于函数参数，应该尽量控制在三个以内，一个最好。如果入参过多，应该将他们用一个实体类封装起来。别用标识参数，向函数传入 bool 值是不好的，这意味着函数不止做一件事。可以将此函数拆成两个
• 可以使用异常代替返回错误码，DDD 中也这么建议，在 app 层以及以上的层级，应该直接抛出异常
• 不要写重复代码，重复是软件中一切邪恶的根源。当算法改变时需要修改多处地方
• 写函数时，可以使用一个函数先写一个整体的业务逻辑，写完之后进行拆分
• 分离指令和查询。每个函数要么是查询操作，要么对数据做算法操作，不应该将它们混合在一起，甚至应该整理这两类操作，将它们分离到不同的类中去

注释

• 若编程语言足够有表现力，我们就不需要注释。注释总是一种失败，因为代码在演化，注释却不总是随之变动，同时不准确的注释比没注释坏的多
• 用代码来阐述，只有在不可避免的情况下才使用注解
• 一些显而易见容易理解的方法不要用注解
• 好注释会提供基本信息，如解释某个抽象方法的返回值；对意图的解释，反应了作者某个决定后面的意图；阐释。把某些晦涩的参数或者返回值的意义翻译成可读的形式（更好的方法是让它们自身变得足够清晰，但是类似标准库的代码我们无法修改）

格式

垂直格式

• 短文件比长文件更易于理解。平均200行，最多不超过500行的单个文件可以构造出色的系统
• 紧密相关的代码应该互相靠近，例如一个类里的属性之间别用空白行隔开，变量声明应尽可能靠近其使用位置：循环中的控制变量应该总是在循环语句中声明。
• 成员变量应该放在类的顶部声明，不要四处放置
• 如果某个函数调用了另外一个，就应该把它们放在一起。我们希望底层细节最后展现出来，不用沉溺于细节，所以调用者尽可能放在被调用者之上
• 执行同一基础任务的几个函数应该放在一起，比如构造函数、get、set 方法等

水平格式

• 一行代码不必死守80字符的上限，偶尔到达100字符不超过120字符即可
• 区隔与靠近: 空格强调左右两边的分割。赋值运算符两边加空格，函数名与左圆括号之间不加空格，乘法运算符在与加减法运算符组合时不用加空格(a*b - c)
• 不必水平对齐。例如声明一堆成员变量时，各行不用每一个单词都对齐。
• 短小的if、while、函数里最好也不要违反缩进规则，不要这样： if (xx == yy) z = 1;
• Ctrl + Alt + L 能解决大多数水平格式问题

数据结构与对象

数据结构封装数据，没有明显的行为（接口），对象封装函数，没有向外暴露的数据，分清两者该干什么有利于我们理清代码层次关系

使用数据结构便于在不改动现在数据结构的前提下添加新函数；使用对象便于在不改动既有函数的前提下添加新类。使用数据结构难以添加新数据结构，因为必须修改所有函数；使用对象难以添加新函数，因为必须修改所有类

模块不应该了解它所操作对象的内部情形，人可以命令一条狗行走（walk），但是不应该直接指挥狗的腿行走，应该由狗去指挥控制它的腿如何行走，函数也该是如此，要保证在某个行为中调用函数的抽象层级一致

这也是设计模式中的最少知道原则

空值处理

空指针问题至少每年造成了十亿级别的金额损耗，我们要额外重视对空指针问题的处理

• 别返回 null 值，返回null值只要一处没检查 null，应用程序就会失败，当想返回 null 值的时候，可以试试抛出异常，或者返回特例模式的对象，java8 与 guava 已经为我们提供了解决方案
• 别传递 null 值，在方法中传递 null 值是一种糟糕的做法，应该尽量避免。在方法里用 if 或 assert 过滤 null 值参数，但是还是会出现运行时错误，没有良好的办法对付调动者意外传入的 null 值，恰当的做法就是禁止传入 null 值
• 多多使用 Objects.equals，减少空指针。比如一些 Boolean 类型的值，如果直接使用三目表达式就会出错，但是如果使用 Objects.equals 就没问题了
• 如果不使用 DDD 的话，拿到每个数都做判空处理。这样最稳妥也最臃肿
• 就需要将下层和上层逻辑切开，判空逻辑在下层做，数据给到上层时，保证数据的合理性

边界

DDD 建议我们在调用三方代码的时候统一做一个防腐层，也就是将自己的代码与三方的代码做隔离，这么做是为了防止其他的腐烂味道传染进来

• 避免公共 API 返回边界接口，或者将边界接口作为参数传递给 API。将边界保留在近亲类中
• 不要在生产代码中试验新东西，而是编写测试来理解第三方代码。这些学习性测试没有任何副作用确受益良多
• 避免我们的代码过多地了解第三方代码中的特定信息
• 使用尚不存在的代码，在代码中总是有很多地方是我们没有设计到的，我们不可能一接手一个项目就将它的所有底层都搭好。此时我们在上层可以使用一个还没有写出来的函数，这个函数接受某些数据，实现了某些功能，都可以定义好

测试

F.I.R.S.T

• 快速（Fast）测试应该够快
• 独立（Independent）测试应该相互独立
• 可重复（Repeatable）测试应当可在任何环境中重复通过
• 自足验证（Self-Validating）测试应该有布尔值输出，自己就能给出对错，而不需要通过看日志，比对结果等方式验证
• 及时（Timely）测试应及时编写

TDD 三定律

• 在编写能通过的单元测试前，不可编写生产代码（测试先行）
• 只可编写刚好无法通过的单元测试，不能编译也算不通过（测试一旦失败，开始写生产代码）
• 只可编写刚好足以通过当前失败测试的生产代码（老测试一旦通过，返回写新测试）

整洁的测试

• 三个要素：可读性、可读性和可读性，明确、简洁还有足够的表达力
• 构造-操作-检验（BUILD-OPERATE-CHECK）模式，第一个环节构造测试数据，第二个环节操作测试数据，第三个部分检验操作是否得到期望的结果
• 守规矩的开发者也将他们的测试代码重构为更简洁和具有表达力的形式

类

一些变量与方法构成了一个类，我们一般写代码的习惯就是变量列表开始，如果有公共静态变量，应该先出现，然后是私有静态变量，以及实体变量，很少会有公共变量，公共函数应该跟在变量列表之后

与函数相似，它们都应该短小，职责单一。而我们之前听说过的高内聚低耦合中，高内聚的意思就是方法操作的变量越多，就越黏聚到类上，如果一个类的每个变量都被每个方法所使用，则该类具有最大的内聚性

比如 DDD 中带状态的 entity，就有很高的内聚性，它指定一些变量和方法，而这些方法只对类中的变量做操作

开放-闭合原则（OCP）：类应当对扩展开放，对修改封闭

依赖倒置原则：类应该依赖于抽象而不是依赖于具体细节