|
|
|
|
@ -2,10 +2,10 @@
|
|
|
|
|
|
|
|
|
|
## 第一章 基础编码规范
|
|
|
|
|
### 1.1 命名规范
|
|
|
|
|
- 代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。
|
|
|
|
|
- 代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。
|
|
|
|
|
tips：JDK动态代理生成的代理类 类名使用了\$符号开头，如\$Proxy1。
|
|
|
|
|
|
|
|
|
|
- 代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。
|
|
|
|
|
- 代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。
|
|
|
|
|
tips：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，即使纯拼音命名方式也要避免采用。alibaba，yonyou，Beijing等国际通用的名称，可视同英文。
|
|
|
|
|
在我们的财务相关模块的工程代码及数据库表设计中，可以看到一些拼音首字母缩写的命名方式，如：arap_djzb，arap是“应收应付”的英文缩写，djzb是“单据主表”的汉语拼音首字母，zdr、shr、lrr都是汉语拼音首字母缩写。当然，这些都是历史包袱，经历了这么多年的代码积累，很难从底层去修正咯，但在自己的实际编码中要以史为鉴，让自己的代码更加优雅规范，这也是同事是否尊重你的重要考量之一。
|
|
|
|
|
|
|
|
|
|
@ -13,7 +13,7 @@ tips：正确的英文拼写和语法可以让阅读者易于理解，避免歧
|
|
|
|
|
PO / UID等。
|
|
|
|
|
tips：合理的类名后缀能够让我们在开发中快速地找到自己想要的代码，想看某个业务层就ctrl + shift + T搜索“XXXBO”，想看某展示层代码 就搜索“XXXVO”。
|
|
|
|
|
|
|
|
|
|
- 抽象类命名使用 Abstract 或 Base 开头；异常类命名使用 Exception 结尾；测试类命名以它要测试的类的名称开始，以 Test 结尾。
|
|
|
|
|
- 抽象类命名使用 Abstract 或 Base 开头；异常类命名使用 Exception 结尾；测试类命名以它要测试的类的名称开始，以 Test 结尾。
|
|
|
|
|
例如：Spring框架的AbstractApplicationContext和Mybatis框架的BaseExecutor都是抽象类。
|
|
|
|
|
|
|
|
|
|
- 方法名、参数名、成员变量、局部变量都统一使用lowerCamelCase——小驼峰风格。
|
|
|
|
|
@ -65,7 +65,7 @@ A) Service/DAO 层方法命名规约
|
|
|
|
|
3） 获取统计值的方法用 count 做前缀。
|
|
|
|
|
4） 插入的方法用 save/insert 做前缀。
|
|
|
|
|
5） 删除的方法用 remove/delete 做前缀。
|
|
|
|
|
6） 修改的方法用 update 做前缀。
|
|
|
|
|
6） 修改的方法用 update 做前缀。
|
|
|
|
|
B) 领域模型命名规约
|
|
|
|
|
1） 数据对象：xxxDO，xxx 即为数据表名。
|
|
|
|
|
2） 数据传输对象：xxxDTO，xxx 为业务领域相关的名称。
|
|
|
|
|
@ -92,9 +92,9 @@ cache.put(key, value);
|
|
|
|
|
类 A 中：public static final String YES = "yes"；
|
|
|
|
|
类 B 中：public static final String YES = "y"；
|
|
|
|
|
A.YES.equals(B.YES)，预期是 true，但实际返回为 false，导致线上问题。
|
|
|
|
|
3）子工程内部共享常量：即在当前子工程的 constant 目录下。
|
|
|
|
|
4） 包内共享常量：即在当前包下单独的 constant 目录下。
|
|
|
|
|
5） 类内共享常量：直接在类内部 private static final 定义。
|
|
|
|
|
3）子工程内部共享常量：即在当前子工程的 constant 目录下。
|
|
|
|
|
4）包内共享常量：即在当前包下单独的 constant 目录下。
|
|
|
|
|
5）类内共享常量：直接在类内部 private static final 定义。
|
|
|
|
|
|
|
|
|
|
- 如果变量值仅在一个固定范围内变化用 enum 类型来定义。
|
|
|
|
|
说明：如果存在名称之外的延伸属性应使用 enum 类型，下面正例中的数字就是延伸信息，表示一年中的第几个季节。
|
|
|
|
|
@ -119,7 +119,8 @@ public enum SeasonEnum {
|
|
|
|
|
- 所有的覆写方法，必须加@Override 注解。
|
|
|
|
|
说明：getObject()与 get0bject()的问题。一个是字母的 O，一个是数字的 0，加@Override 可以准确判断是否覆盖成功。另外，如果在抽象类中对方法签名（由方法名、参数的类型及**顺序** 确定唯一的方法签名）进行修改，其实现类会马上编译报错。
|
|
|
|
|
|
|
|
|
|
- 相同参数类型，相同业务含义，才可以使用 Java 的可变参数，避免使用 Object。 说明：可变参数必须放置在参数列表的最后。（能用数组的就不要使用可变参数编程，可变参数在编译时会被编译成数组类型。可变参数能兼容数组类参数，但是数组类参数却无法兼容可变参数。可变参数类型必须作为参数列表的最后一项，且不能放在定长参数的前面。）
|
|
|
|
|
- 相同参数类型，相同业务含义，才可以使用 Java 的可变参数，避免使用 Object。
|
|
|
|
|
说明：可变参数必须放置在参数列表的最后。（能用数组的就不要使用可变参数编程，可变参数在编译时会被编译成数组类型。可变参数能兼容数组类参数，但是数组类参数却无法兼容可变参数。可变参数类型必须作为参数列表的最后一项，且不能放在定长参数的前面。）
|
|
|
|
|
正例：public List<User> listUsers(String type, Long... ids) {...}
|
|
|
|
|
|
|
|
|
|
- 外部正在调用或者二方库依赖的接口，不允许修改方法签名，避免对接口调用方产生影响。接口过时必须加@Deprecated 注解，并清晰地说明采用的新接口或者新服务是什么。
|
|
|
|
|
@ -156,7 +157,8 @@ tips：
|
|
|
|
|
- **构造方法里面禁止加入任何业务逻辑，如果有初始化逻辑，请放在 init() 方法中。**
|
|
|
|
|
在很多client端的代码中有看到这种编码方式。
|
|
|
|
|
|
|
|
|
|
- POJO 类必须写 toString() 方法。使用 IDE 中的工具：source -> generate toString() 时，如果继承了另一个 POJO 类，注意在前面加一下 super.toString()。 说明：在方法执行抛出异常时，可以直接调用 POJO 的 toString()方法打印其属性值，便于排查问题。
|
|
|
|
|
- POJO 类必须写 toString() 方法。使用 IDE 中的工具：source -> generate toString() 时，如果继承了另一个 POJO 类，注意在前面加一下 super.toString()。
|
|
|
|
|
说明：在方法执行抛出异常时，可以直接调用 POJO 的 toString()方法打印其属性值，便于排查问题。
|
|
|
|
|
|
|
|
|
|
- 当一个类有多个构造方法，或者多个同名方法，这些方法应该按顺序放置在一起， 便于阅读。
|
|
|
|
|
|
|
|
|
|
@ -217,7 +219,8 @@ array = list.toArray(array);
|
|
|
|
|
String[] strs = list.toArray(new String[0]);
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
- 使用工具类 Arrays.asList()把数组转换成集合时，不能使用其修改集合相关的方法，它的add/remove/clear 方法会抛出 UnsupportedOperationException 异常。 说明：asList() 的返回对象是一个 Arrays 的内部类ArrayList（而不是java.util.ArrayList），该内部类 并没有实现集合的修改/删除等方法。Arrays.asList 体现的是适配器模式，只是转换接口，后台的数据仍是数组。
|
|
|
|
|
- 使用工具类 Arrays.asList()把数组转换成集合时，不能使用其修改集合相关的方法，它的add/remove/clear 方法会抛出 UnsupportedOperationException 异常。
|
|
|
|
|
说明：asList() 的返回对象是一个 Arrays 的内部类ArrayList（而不是java.util.ArrayList），该内部类 并没有实现集合的修改/删除等方法。Arrays.asList 体现的是适配器模式，只是转换接口，后台的数据仍是数组。
|
|
|
|
|
```java
|
|
|
|
|
String[] str = new String[] { "you", "wu" };
|
|
|
|
|
List list = Arrays.asList(str);
|
|
|
|
|
@ -263,7 +266,8 @@ for (String item : list) {
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
- 在 JDK7 版本及以上，Comparator 实现类要满足如下三个条件，不然 Arrays.sort()， Collections.sort() 会报 IllegalArgumentException 异常。 说明：三个条件如下 1） x，y 的比较结果和 y，x 的比较结果相反。 2） x>y，y>z，则 x>z。 3） x=y，则 x，z 比较结果和 y，z 比较结果相同。
|
|
|
|
|
- 在 JDK7 版本及以上，Comparator 实现类要满足如下三个条件，不然 Arrays.sort()， Collections.sort() 会报 IllegalArgumentException 异常。
|
|
|
|
|
说明：三个条件如下 1） x，y 的比较结果和 y，x 的比较结果相反。 2） x>y，y>z，则 x>z。 3） x=y，则 x，z 比较结果和 y，z 比较结果相同。
|
|
|
|
|
```java
|
|
|
|
|
// 反例：下例中没有处理相等的情况，实际使用中可能会出现异常：
|
|
|
|
|
new Comparator<Student>() {
|
|
|
|
|
@ -444,7 +448,8 @@ public void today() {
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
- 除常用方法（如 getXxx/isXxx）等外，不要在条件判断中执行其它复杂的语句，将复杂逻辑判断的结果赋值给一个有意义的布尔变量名，以提高可读性。 说明：很多 if 语句内的逻辑相当复杂，阅读者需要分析条件表达式的最终结果，才能明确什么样的条件执行什么样的语句，那么，如果阅读者分析逻辑表达式错误呢？
|
|
|
|
|
- 除常用方法（如 getXxx/isXxx）等外，不要在条件判断中执行其它复杂的语句，将复杂逻辑判断的结果赋值给一个有意义的布尔变量名，以提高可读性。
|
|
|
|
|
说明：很多 if 语句内的逻辑相当复杂，阅读者需要分析条件表达式的最终结果，才能明确什么样的条件执行什么样的语句，那么，如果阅读者分析逻辑表达式错误呢？
|
|
|
|
|
```java
|
|
|
|
|
// 正例：
|
|
|
|
|
// 伪代码如下
|
|
|
|
|
@ -501,11 +506,11 @@ if ((file.open(fileName, "w") != null) && (...) || (...)) {
|
|
|
|
|
|
|
|
|
|
- 谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除。
|
|
|
|
|
说明：代码被注释掉有两种可能性。
|
|
|
|
|
1）后续会恢复此段代码逻辑。
|
|
|
|
|
1）后续会恢复此段代码逻辑。
|
|
|
|
|
2）永久不用。前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉（代码仓库保存了历史代码）。
|
|
|
|
|
|
|
|
|
|
- 对于注释的要求：
|
|
|
|
|
第一、能够准确反应设计思想和代码逻辑；
|
|
|
|
|
第一、能够准确反应设计思想和代码逻辑；
|
|
|
|
|
第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作。
|
|
|
|
|
|
|
|
|
|
- 好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。
|
|
|
|
|
@ -535,7 +540,8 @@ put(elephant, fridge);
|
|
|
|
|
- 获取当前毫秒数 System.currentTimeMillis(); 而不是 new Date().getTime();
|
|
|
|
|
说明：如果想获取更加精确的纳秒级时间值，使用 System.nanoTime()的方式。在 JDK8 中， 针对统计时间等场景，推荐使用 Instant 类。
|
|
|
|
|
|
|
|
|
|
- 不要在视图模板中加入任何复杂的逻辑。 说明：根据 MVC 理论，视图的职责是展示，不要抢模型和控制器的活。
|
|
|
|
|
- 不要在视图模板中加入任何复杂的逻辑。
|
|
|
|
|
说明：根据 MVC 理论，视图的职责是展示，不要抢模型和控制器的活。
|
|
|
|
|
|
|
|
|
|
- 任何数据结构的构造或初始化，都应指定大小，避免数据结构无限增长吃光内存。
|
|
|
|
|
|
|
|
|
|
@ -550,7 +556,8 @@ put(elephant, fridge);
|
|
|
|
|
正例：if (obj != null) {...}
|
|
|
|
|
反例：try { obj.method(); } catch (NullPointerException e) {…}
|
|
|
|
|
|
|
|
|
|
- 异常不要用来做流程控制，条件控制。 说明：异常设计的初衷是解决程序运行中的各种意外情况，且异常的处理效率比条件判断方式要低很多。
|
|
|
|
|
- 异常不要用来做流程控制，条件控制。
|
|
|
|
|
说明：异常设计的初衷是解决程序运行中的各种意外情况，且异常的处理效率比条件判断方式要低很多。
|
|
|
|
|
|
|
|
|
|
- catch 时请分清稳定代码和非稳定代码，稳定代码指的是无论如何不会出错的代码。 对于非稳定代码的 catch 尽可能进行区分异常类型，再做对应的异常处理。
|
|
|
|
|
说明：对大段代码进行 try-catch，使程序无法根据不同的异常做出正确的应激反应，也不利于定位问题，这是一种不负责任的表现。
|
|
|
|
|
@ -589,7 +596,8 @@ put(elephant, fridge);
|
|
|
|
|
1）使用抛异常返回方式，调用方如果没有捕获到就会产生运行时错误。
|
|
|
|
|
2）如果不加栈信息，只是 new 自定义异常，加入自己的理解的 error message，对于调用端解决问题的帮助不会太多。如果加了栈信息，在频繁调用出错的情况下，数据序列化和传输的性能损耗也是问题。
|
|
|
|
|
|
|
|
|
|
- 避免出现重复的代码（Don’t Repeat Yourself），即 DRY 原则。 说明：随意复制和粘贴代码，必然会导致代码的重复，在以后需要修改时，需要修改所有的副本，容易遗漏。必要时抽取共性方法，或者抽象公共类，甚至是组件化。
|
|
|
|
|
- 避免出现重复的代码（Don’t Repeat Yourself），即 DRY 原则。
|
|
|
|
|
说明：随意复制和粘贴代码，必然会导致代码的重复，在以后需要修改时，需要修改所有的副本，容易遗漏。必要时抽取共性方法，或者抽象公共类，甚至是组件化。
|
|
|
|
|
```java
|
|
|
|
|
// 正例：
|
|
|
|
|
// 一个类中有多个 public 方法，都需要进行数行相同的参数校验操作，这个时候请抽取：
|
|
|
|
|
@ -671,7 +679,7 @@ tips：我们使用的是dr字段代表逻辑删除，且POJO和布尔字段也
|
|
|
|
|
- 如果存储的字符串长度几乎相等，使用 char 定长字符串类型。
|
|
|
|
|
tips：公司这一点倒是做的比较规范。
|
|
|
|
|
|
|
|
|
|
- varchar 是不定长字符串，不预先分配存储空间，长度不要超过 5000，如果存储长度大于此值，定义字段类型为 text，独立出来一张表，用主键来对应，避免影响其它字段索引效率。
|
|
|
|
|
- varchar 是不定长字符串，不预先分配存储空间，长度不要超过 5000，如果存储长度大于此值，定义字段类型为 text，独立出来一张表，用主键来对应，避免影响其它字段索引效率。
|
|
|
|
|
tips：Oracle的varchar最大长度为4000，SQL server 8000，这是之前适配数据库时踩过的坑。
|
|
|
|
|
|
|
|
|
|
- 表必备三字段：id, gmt_create, gmt_modified。
|
|
|
|
|
|
AmyliaY
5 years ago