代码规范整理

这一秒不放弃，下一秒有奇迹

代码规范整理

命名风格

1. 代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。
2. 使用英文命名。
3. 采用驼峰命名法。DO / BO / DTO / VO / AO / PO / UID 等例外。
4. 方法名、参数名、成员变量、局部变量必须存储驼峰形式。
5. 常量全部大写英文，单词见用下划线隔开，不要嫌长。
6. 抽象类命名使用 Abstract 或 Base 开头； 异常类命名使用 Exception 结尾； 测试类命名以它要测试的类的名称开始，以 Test 结尾。
7. 类型与中括号紧挨相连来表示数组。 int[] arrayDemo
8. POJO 类中布尔类型的变量，都不要加 is 前缀，否则部分框架解析会引起序列化错误。
9. 包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式。
10. 杜绝完全不规范的缩写， 避免望文不知义。
11. 如果模块、 接口、类、方法使用了设计模式，在命名时需体现出具体模式。
12. 接口类中的方法和属性不要加任何修饰符号（public 也不要加） ，保持代码的简洁
    性，并加上有效的 Javadoc 注释。
13. 对于 Service 和 DAO 类，基于 SOA 的理念，暴露出来的服务一定是接口，内部的实现类用 Impl 的后缀与接口区别。
14. 如果是形容能力的接口名称，取对应的形容词为接口名（通常是–able 的形式） 。AbstractTranslator 实现 Translatable 接口。
15. 枚举类名建议带上 Enum 后缀，枚举成员名称需要全大写，单词间用下划线隔开。
16. 各层命名规约：
    A) Service/DAO 层方法命名规约
    1） 获取单个对象的方法用 get 做前缀。
    2） 获取多个对象的方法用 list 做前缀，复数形式结尾如： listObjects。
    3） 获取统计值的方法用 count 做前缀。
    4） 插入的方法用 save/insert 做前缀。
    5） 删除的方法用 remove/delete 做前缀。
    6） 修改的方法用 update 做前缀。
    B) 领域模型命名规约
    1） 数据对象： xxxDO， xxx 即为数据表名。
    2） 数据传输对象： xxxDTO， xxx 为业务领域相关的名称。
    3） 展示对象： xxxVO， xxx 一般为网页名称。
    4） POJO 是 DO/DTO/BO/VO 的统称，禁止命名成 xxxPOJO。

常量定义

1. 不允许任何魔法值（即未经预先定义的常量） 直接出现在代码中。
2. 在 long 或者 Long 赋值时， 数值后使用大写的 L，不能是小写的 l，小写容易跟数字 1 混淆，造成误解。
3. 不要使用一个常量类维护所有常量， 要按常量功能进行归类，分开维护。
4. 常量的复用层次有五层：跨应用共享常量、应用内共享常量、子工程内共享常量、包内共享常量、类内共享常量。
   1） 跨应用共享常量：放置在二方库中，通常是 client.jar 中的 constant 目录下。
   2） 应用内共享常量：放置在一方库中， 通常是子模块中的 constant 目录下。
   反例： 易懂变量也要统一定义成应用内共享常量，两位攻城师在两个类中分别定义了表示“是”的变量：
   类 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 定义。
5. 如果变量值仅在一个固定范围内变化用 enum 类型来定义。

代码格式

1. 大括号的使用约定。如果是大括号内为空，则简洁地写成{}即可，不需要换行；如果
   是非空代码块则：
   1） 左大括号前不换行。
   2） 左大括号后换行。
   3） 右大括号前换行。
   4） 右大括号后还有 else 等代码则不换行； 表示终止的右大括号后必须换行。
2. 左小括号和字符之间不出现空格； 同样，右小括号和字符之间也不出现空格；而左大括号前需要空格。
3. if/for/while/switch/do 等保留字与括号之间都必须加空格。
4. 任何二目、 三目运算符的左右两边都需要加一个空格。
5. 采用 4 个空格缩进，禁止使用 tab 字符。可配置
6. 注释的双斜线与注释内容之间有且仅有一个空格。
7. 单行字符数限制不超过 120 个，超出需要换行，换行时遵循如下原则：
   1） 第二行相对第一行缩进 4 个空格，从第三行开始，不再继续缩进，参考示例。
   2） 运算符与下文一起换行。
   3） 方法调用的点符号与下文一起换行。
   4） 方法调用中的多个参数需要换行时， 在逗号后进行。
   5） 在括号前不要换行，见反例。
8. 方法参数在定义和传入时，多个参数逗号后边必须加空格。
9. 单个方法的总行数不超过 80 行。包括方法签名、结束右大括号、方法内代码、注释、空行、回车及任何不可见字符的总行数不超过 80 行。
10. 有必要增加若干空格来使某一行的字符与上一行对应位置的字符对齐。
11. 不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性。任何情形， 没有必要插入多个空行进行隔开。

OOP 规约

1. 避免通过一个类的对象引用访问此类的静态变量或静态方法，无谓增加编译器解析成
   本，直接用类名来访问即可。
2. 所有的覆写方法，必须加@Override 注解。
3. 相同参数类型，相同业务含义，才可以使用 Java 的可变参数，避免使用 Object。
4. 外部正在调用或者二方库依赖的接口，不允许修改方法签名，避免对接口调用方产生影响。接口过时必须加@Deprecated 注解，并清晰地说明采用的新接口或者新服务是什么。
5. 不能使用过时的类或方法。
6. Object 的 equals 方法容易抛空指针异常，应使用常量或确定有值的对象来调用equals。推荐使用 java.util.Objects#equals（JDK7 引入的工具类）
7. 所有的相同类型的包装类对象之间值的比较，全部使用 equals 方法比较。对于 Integer var = ? 在-128 至 127 范围内的赋值， Integer 对象是在IntegerCache.cache 产生，会复用已有对象，这个区间内的 Integer 值可以直接使用==进行判断，但是这个区间之外的所有数据，都会在堆上产生，并不会复用已有对象，这是一个大坑，推荐使用 equals 方法进行判断。
8. 关于基本数据类型与包装数据类型的使用标准如下：
   1）所有的 POJO 类属性必须使用包装数据类型。
   2）RPC 方法的返回值和参数必须使用包装数据类型。
   3）所有的局部变量使用基本数据类型。
   POJO 类属性没有初值是提醒使用者在需要使用时，必须自己显式地进行赋值，任何NPE 问题，或者入库检查，都由使用者来保证
9. 定义 DO/DTO/VO 等 POJO 类时，不要设定任何属性默认值。
10. 序列化类新增属性时，请不要修改 serialVersionUID 字段，避免反序列失败； 如果完全不兼容升级，避免反序列化混乱，那么请修改 serialVersionUID 值。
11. 构造方法里面禁止加入任何业务逻辑，如果有初始化逻辑，请放在 init 方法中。
12. POJO 类必须写 toString 方法。使用 IDE 中的工具： source> generate toString时，如果继承了另一个 POJO 类，注意在前面加一下 super.toString。
13. 禁止在 POJO 类中，同时存在对应属性 xxx 的 isXxx()和 getXxx()方法。
14. 使用索引访问用 String 的 split 方法得到的数组时，需做最后一个分隔符后有无内容的检查，否则会有抛 IndexOutOfBoundsException 的风险。
15. 当一个类有多个构造方法，或者多个同名方法，这些方法应该按顺序放置在一起。
16. 类内方法定义的顺序依次是：公有方法或保护方法 > 私有方法 > getter/setter
    方法
17. setter 方法中，参数名称与类成员变量名称一致， this.成员名 = 参数名。在getter/setter 方法中， 不要增加业务逻辑，增加排查问题的难度。
18. 循环体内，字符串的连接方式，使用 StringBuilder 的 append 方法进行扩展。
19. final 可以声明类、成员变量、方法、以及本地变量，下列情况使用 final 关键字：
    1） 不允许被继承的类，如： String 类。
    2） 不允许修改引用的域对象。
    3） 不允许被重写的方法，如： POJO 类的 setter 方法。
    4） 不允许运行过程中重新赋值的局部变量。
    5） 避免上下文重复使用一个变量，使用 final 描述可以强制重新定义一个变量，方便更好地进行重构。
20. 慎用 Object 的 clone 方法来拷贝对象。
21. 类成员与方法访问控制从严：
    1） 如果不允许外部直接通过 new 来创建对象，那么构造方法必须是 private。
    2） 工具类不允许有 public 或 default 构造方法。
    3） 类非 static 成员变量并且与子类共享，必须是 protected。
    4） 类非 static 成员变量并且仅在本类使用，必须是 private。
    5） 类 static 成员变量如果仅在本类使用，必须是 private。
    6） 若是 static 成员变量， 考虑是否为 final。
    7） 类成员方法只供类内部调用，必须是 private。
    8） 类成员方法只对继承类公开，那么限制为 protected。

集合处理

1. 关于 hashCode 和 equals 的处理，遵循如下规则：
   1） 只要重写 equals，就必须重写 hashCode。
   2） 因为 Set 存储的是不重复的对象，依据 hashCode 和 equals 进行判断，所以 Set 存储的对象必须重写这两个方法。
   3） 如果自定义对象作为 Map 的键，那么必须重写 hashCode 和 equals。
2. ArrayList的subList结果不可强转成ArrayList，否则会抛出 ClassCastException异常， 即 java.util.RandomAccessSubList cannot be cast to java.util.ArrayList。
3. 在 subList 场景中， 高度注意对原集合元素的增加或删除， 均会导致子列表的遍历、增加、删除产生 ConcurrentModificationException 异常
4. 使用集合转数组的方法，必须使用集合的 toArray(T[] array)，传入的是类型完全一样的数组，大小就是 list.size()。
5. 使用工具类 Arrays.asList()把数组转换成集合时，不能使用其修改集合相关的方法，它的 add/remove/clear 方法会抛出 UnsupportedOperationException 异常。
6. 泛型通配符来接收返回的数据，此写法的泛型集合不能使用 add 方法， 而不能使用 get 方法，作为接口调用赋值时易出错。
7. 不要在 foreach 循环里进行元素的 remove/add 操作。 remove 元素请使用 Iterator方式，如果并发操作，需要对 Iterator 对象加锁。
8. 在 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 比较结果相同。
9. 集合泛型定义时， 在 JDK7 及以上，使用 diamond 语法或全省略。
10. 集合初始化时， 指定集合初始值大小。
11. 使用 entrySet 遍历 Map 类集合 KV，而不是 keySet 方式进行遍历。
12. 高度注意 Map 类集合 K/V 能不能存储 null 值的情况。
13. 合理利用好集合的有序性(sort)和稳定性(order)，避免集合的无序性(unsort)和不稳定性(unorder)带来的负面影响。
14. 利用 Set 元素唯一的特性，可以快速对一个集合进行去重操作，避免使用 List 的contains 方法进行遍历、对比、 去重操作。

控制语句

1. 在一个 switch 块内，每个 case 要么通过 break/return 等来终止，要么注释说明程序将继续执行到哪一个 case 为止； 在一个 switch 块内，都必须包含一个 default 语句并且放在最后，即使空代码。
2. 在 if/else/for/while/do 语句中必须使用大括号。 即使只有一行代码，避免采用单行的编码方式： if (condition) statements;
3. 在高并发场景中，避免使用”等于”判断作为中断或退出的条件。如果并发控制没有处理好，容易产生等值判断被“击穿”的情况，使用大于或小于的区间判断条件来代替。
4. 表达异常的分支时， 少用 if-else 方式，如果需要使用，绝对不要超过3层。
5. 除常用方法（如 getXxx/isXxx）等外，不要在条件判断中执行其它复杂的语句，将复杂逻辑判断的结果赋值给一个有意义的布尔变量名，以提高可读性。
6. 循环体中的语句要考量性能，以下操作尽量移至循环体外处理，如定义对象、变量、获取数据库连接，进行不必要的 try-catch 操作（这个 try-catch 是否可以移至循环体外） 。
7. 避免采用取反逻辑运算符。
8. 下列情形，需要进行参数校验：
   1） 调用频次低的方法。
   2） 执行时间开销很大的方法。 此情形中， 参数校验时间几乎可以忽略不计，但如果因为参数错误导致中间执行回退，或者错误，那得不偿失。
   3） 需要极高稳定性和可用性的方法。
   4） 对外提供的开放接口，不管是 RPC/API/HTTP 接口。
   5） 敏感权限入口。
9. 下列情形， 不需要进行参数校验：
   1） 极有可能被循环调用的方法。但在方法说明里必须注明外部参数检查要求。
   2） 底层调用频度比较高的方法。毕竟是像纯净水过滤的最后一道，参数错误不太可能到底层才会暴露问题。一般 DAO 层与 Service 层都在同一个应用中，部署在同一台服务器中，所以 DAO 的参数校验，可以省略。
   3） 被声明成 private 只会被自己代码所调用的方法，如果能够确定调用方法的代码传入参数已经做过检查或者肯定不会有问题，此时可以不校验参数。

注释规约

1. 类、类属性、类方法的注释必须使用 Javadoc 规范，使用/*内容/格式，不得使用 // xxx 方式。
2. 有的抽象方法（包括接口中的方法） 必须要用 Javadoc 注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。
3. 所有的类都必须添加创建者和创建日期。
4. 方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。
5. 所有的枚举类型字段必须要有注释，说明每个数据项的用途。
6. 与其“半吊子”英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可。
7. 代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。
8. 谨慎注释掉代码。 在上方详细说明，而不是简单地注释掉。 如果无用，则删除。
9. 对于注释的要求：第一、能够准确反应设计思想和代码逻辑； 第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路； 注释也是给继任者看的，使其能够快速接替自己的工作。
10. 好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。

日复一日