代码规范学习笔记（待补充）

编程规约

（一）命名风格

1、代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。

2、代码中命名严禁使用拼音与英文混合方式，更不允许使用中文的方式，应当使用正确的英语单词或语法拼写。

3、类名使用UpperCamelCase风格，但以下情形例外：DO / BO / DTO / VO / AO / PO等。

4、方法名、参数名、成员变量、局部变量统一使用lowerCamelCase风格，必须遵守驼峰形式。

5、常量命名全部大写，单词间用下划线隔开，力求语义表达完整，不用嫌弃过长。

6、抽象类命名使用Abstract或Base开头；异常类命名使用Exception结尾；测试类命名以它要测试的类名开始，以Test结尾。

7、类型与中括号紧挨相连来定义数组。

8、POJO类中布尔类型的变量，都不要加is前缀，否则部分框架解析会引起序列化错误。

9、包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式。

10、杜绝完全不规范的缩写，避免望文不知义。

11、如果模块、接口、类、方法使用了设计模式，在命名时体现出具体模式。

12、接口类中的方法和属性不要加任何修饰符号（public 也不要加），保持代码的简洁性，并加上有效的Javadoc注释。尽量不要在接口里定义变量，如果一定要定义变量，肯定是与接口方法相关，并且是整个应用的基础常量。

13、接口和实现类的命名有两套规则：

　　1）对于Service和DAO类，基于SOA的理念，暴露出来的服务一定是接口，内部的实现类用Impl的后缀与接口区别。

　　2）如果是形容能力的接口名称，取对应的形容词为接口名（通常是–able的形式）。

14、枚举类名建议带上Enum后缀，枚举成员名称需要全大写，单词间用下划线隔开。

15、【参考】各层命名规约：
　　A) Service/DAO层方法命名规约
　　1） 获取单个对象的方法用get作前缀。
　　2） 获取多个对象的方法用list作前缀。
　　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目录下。

　　3） 子工程内部共享常量：即在当前子工程的constant目录下。

　　4） 包内共享常量：即在当前包下单独的constant目录下。

　　5） 类内共享常量：直接在类内部private static final定义。

5、【推荐】如果变量值仅在一个固定范围内变化用enum类型来定义。 说明：如果存在名称之外的延伸属性使用enum类型。

 

（三）代码格式

1、大括号的使用约定。如果是大括号内为空，则简洁地写成{}即可，不需要换行；如果是非空代码块则：

　　1） 左大括号前不换行。
　　2） 左大括号后换行。
　　3） 右大括号前换行。
　　4） 右大括号后还有else等代码则不换行；表示终止的右大括号后必须换行。

2、左小括号和字符之间不出现空格；同样，右小括号和字符之间也不出现空格。

3、if/for/while/switch/do等保留字与括号之间都必须加空格。

4、任何二目、三目运算符的左右两边都需要加一个空格。

5、采用4个空格缩进，禁止使用tab字符。如果使用，请设置Tab为4个空格。

6、注释的双斜线与注释内容之间有且仅有一个空格。

7、单行字符数限制不超过120个，超出需要换行，换行时遵循如下原则：
　　1）第二行相对第一行缩进4个空格，从第三行开始，不再继续缩进，参考示例。
　　2）运算符与下文一起换行。
　　3）方法调用的点符号与下文一起换行。
　　4） 方法调用时，多个参数，需要换行时，在逗号后进行。
　　5） 在括号前不要换行。

8、方法参数在定义和传入时，多个参数逗号后边必须加空格。

9、IDE的text file encoding设置为UTF-8; IDE中文件的换行符使用Unix格式，不要使用Windows格式。

10、【推荐】不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性。

 

（四）OPP规约

1、避免通过一个类的对象引用访问此类的静态变量或静态方法，无谓增加编译器解析成本，直接用类名来访问即可。

2、所有的覆写方法，必须加@Override注解。

3、相同参数类型，相同业务含义，才可以使用Java的可变参数，避免使用Object。

4、外部正在调用或者二方库依赖的接口，不允许修改方法签名，避免对接口调用方产生影响。接口过时必须加@Deprecated注解，并清晰地说明采用的新接口或者新服务是什么。

5、不能使用过时的类或方法。

6、Object的equals方法容易抛空指针异常，应使用常量或确定有值的对象来调用equals。

7、所有的相同类型的包装类对象之间值的比较，全部使用equals方法比较。

8、关于基本数据类型与包装数据类型的使用标准如下：

　　1）所有的POJO类属性必须使用包装数据类型。
　　2）RPC方法的返回值和参数必须使用包装数据类型。
　　3）【推荐】所有的局部变量使用基本数据类型。

9、定义DO/DTO/VO等POJO类时，不要设定任何属性默认值。

10、序列化类新增属性时，请不要修改serialVersionUID字段，避免反序列失败；如果完全不兼容升级，避免反序列化混乱，那么请修改serialVersionUID值。

11、构造方法里面禁止加入任何业务逻辑，如果有初始化逻辑，请放在init方法中。

12、POJO类必须写toString方法。使用IDE中的工具：source> generate toString时，如果继承了另一个POJO类，注意在前面加一下super.toString。

13、【推荐】使用索引访问用String的split方法得到的数组时，需做最后一个分隔符后有无内容的检查，否则会有抛IndexOutOfBoundsException的风险。

14、【推荐】setter方法中，参数名称与类成员变量名称一致，this.成员名 = 参数名。在getter/setter方法中，不要增加业务逻辑，增加排查问题的难度。

15、【推荐】循环体内，字符串的连接方式，使用StringBuilder的append方法进行扩展。

16、【推荐】final可以声明类、成员变量、方法、以及本地变量，下列情况使用final关键字：

　　1）不允许被继承的类，如：String类。

　　2）不允许修改引用的域对象，如：POJO类的域变量。

　　3）不允许被重用的方法，如：POJO类的setter方法。

　　4）不允许运行过程中重新赋值的局部变量。

　　5）避免上下文重复使用一个变量，使用final描述可以强制重新定义一个变量，方便更好地进行重构。

17、【推荐】慎用Object的clone方法来拷贝对象。

18、【推荐】类成员与方法访问控制从严：
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、泛型通配符<? extends T>来接收返回的数据，此写法的泛型集合不能使用add方法，而<? super T>不能使用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、【推荐】集合初始化时，指定集合初始值大小。
　　说明：HashMap使用HashMap(int initialCapacity) 初始化，
　　正例：initialCapacity = (需要存储的元素个数 / 负载因子) + 1。注意负载因子（即loader factor）默认为0.75，如果暂时无法确定初始值大小，请设置为16（即默认值）。

10、【推荐】使用Map.forEach遍历Map类集合KV，而不是keySet方式进行遍历。

11、【推荐】高度注意Map类集合K/V能不能存储null值的情况，如下表格：

| 集合类            | Key          | Value        | Super       | 说明                   |
|-------------------|--------------|--------------|-------------|------------------------|
| Hashtable         | 不允许为null | 不允许为null | Dictionary  | 线程安全               |
| ConcurrentHashMap | 不允许为null | 不允许为null | AbstractMap | 锁分段技术（JDK8:CAS）  |
| TreeMap           | 不允许为null | 允许为null   | AbstractMap | 线程不安全             |
| HashMap           | 允许为null   | 允许为null   | AbstractMap | 线程不安全             |

12、【参考】利用Set元素唯一的特性，可以快速对一个集合进行去重操作，避免使用List的contains方法进行遍历、对比、去重操作。

 

（六）并发处理

1、获取单例对象需要保证线程安全，其中的方法也要保证线程安全。

2、创建线程或线程池时请指定有意义的线程名称，方便出错时回溯。

3、线程资源必须通过线程池提供，不允许在应用中自行显式创建线程。

4、线程池不允许使用Executors去创建，而是通过ThreadPoolExecutor的方式，这样的处理方式让写的同学更加明确线程池的运行规则，规避资源耗尽的风险。

5、SimpleDateFormat 是线程不安全的类，一般不要定义为static变量，如果定义为static，必须加锁，或者使用DateUtils工具类。

说明：如果是JDK8的应用，可以使用Instant代替Date，LocalDateTime代替Calendar，DateTimeFormatter代替SimpleDateFormat。

6、高并发时，同步调用应该去考量锁的性能损耗。能用无锁数据结构，就不要用锁；能锁区块，就不要锁整个方法体；能用对象锁，就不要用类锁。

7、对多个资源、数据库表、对象同时加锁时，需要保持一致的加锁顺序，否则可能会造成死锁。

8、并发修改同一记录时，避免更新丢失，需要加锁。要么在应用层加锁，要么在缓存加锁，要么在数据库层使用乐观锁，使用version作为更新依据。

　　说明：如果每次访问冲突概率小于20%，推荐使用乐观锁，否则使用悲观锁。乐观锁的重试次数不得小于3次。

9、多线程并行处理定时任务时，Timer运行多个TimeTask时，只要其中之一没有捕获抛出的异常，其它任务便会自动终止运行，使用ScheduledExecutorService则没有这个问题。

10、使用CountDownLatch进行异步转同步操作，每个线程退出前必须调用countDown方法，线程执行代码注意catch异常，确保countDown方法被执行到，避免主线程无法执行至await方法，直到超时才返回结果。

11、【推荐】避免Random实例被多线程使用，虽然共享该实例是线程安全的，但会因竞争同一seed 导致的性能下降。

12、【参考】volatile解决多线程内存不可见问题。对于一写多读，是可以解决变量同步问题，但是如果多写，同样无法解决线程安全问题。如果是count++操作，使用如下类实现：

AtomicInteger count = new AtomicInteger(); 
count.addAndGet(1);

如果是JDK8，推荐使用LongAdder对象，比AtomicLong性能更好（减少乐观锁的重试次数）。

13、【参考】 HashMap在容量不够进行resize时由于高并发可能出现死链，导致CPU飙升，在开发过程中可以使用其它数据结构或加锁来规避此风险。

14、【参考】ThreadLocal无法解决共享对象的更新问题，ThreadLocal对象建议使用static修饰。这个变量是针对一个线程内所有操作共享的，所以设置为静态变量，所有此类实例共享此静态变量 ，也就是说在类第一次被使用时装载，只分配一块存储空间，所有此类的对象(只要是这个线程内定义的)都可以操控这个变量。

 

（七）控制语句

1、在一个switch块内，每个case要么通过break/return等来终止，要么注释说明程序将继续执行到哪一个case为止；在一个switch块内，都必须包含一个default语句并且放在最后，即使空代码。

2、在if/else/for/while/do语句中必须使用大括号。即使只有一行代码，避免采用单行的编码方式

3、在高并发场景中，避免使用”等于”判断作为中断或退出的条件

4、【推荐】除常用方法（如getXxx/isXxx）等外，不要在条件判断中执行其它复杂的语句，将复杂逻辑判断的结果赋值给一个有意义的布尔变量名，以提高可读性。

5、【推荐】循环体中的语句要考量性能，以下操作尽量移至循环体外处理，如定义对象、变量、获取数据库连接，进行不必要的try-catch操作（这个try-catch是否可以移至循环体外）。

 

（八）注释规约

1、类、类属性、类方法的注释必须使用Javadoc规范，使用/*内容/格式，不得使用// xxx方式。

2、所有的抽象方法（包括接口中的方法）必须要用Javadoc注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。

3、所有的类都必须添加创建者和创建日期。

4、方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。

5、所有的枚举类型字段必须要有注释，说明每个数据项的用途。

6、与其“半吊子”英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可。

7、代码修改的同时，注释也要进行相应的修改，尤其是参数、返回值、异常、核心逻辑等的修改。

 

（九）ORM映射

1、在表查询中，一律不要使用 * 作为查询的字段列表，需要哪些字段必须明确写明。

2、POJO类的布尔属性不能加is，而数据库字段必须加is_，要求在resultMap中进行字段与属性之间的映射。

3、不要用resultClass当返回参数，即使所有类属性名与数据库字段一一对应，也需要定义；反过来，每一个表也必然有一个与之对应。

4、sql.xml配置参数使用：#{}，#param# 不要使用${} 此种方式容易出现SQL注入。

5、iBATIS自带的queryForList(String statementName,int start,int size)不推荐使用。

6、不允许直接拿HashMap与Hashtable作为查询结果集的输出。

7、更新数据表记录时，必须同时更新记录对应的gmt_modified字段值为当前时间。

8、不要写一个大而全的数据更新接口。传入为POJO类，不管是不是自己的目标更新字段，都进行update table set c1=value1,c2=value2,c3=value3; 这是不对的。执行SQL时，不要更新无改动的字段，一是易出错；二是效率低；三是增加binlog存储。

 

（十）异常处理

1、Java 类库中定义的可以通过预检查方式规避的RuntimeException异常不应该通过catch 的方式来处理，比如：NullPointerException，IndexOutOfBoundsException等等。 说明：无法通过预检查的异常除外，比如，在解析字符串形式的数字时，不得不通过catch NumberFormatException来实现。

2、异常不要用来做流程控制，条件控制。

3、catch时请分清稳定代码和非稳定代码，稳定代码指的是无论如何不会出错的代码。对于非稳定代码的catch尽可能进行区分异常类型，再做对应的异常处理。

4、捕获异常是为了处理它，不要捕获了却什么都不处理而抛弃之，如果不想处理它，请将该异常抛给它的调用者。最外层的业务使用者，必须处理异常，将其转化为用户可以理解的内容。

5、有try块放到了事务代码中，catch异常后，如果需要回滚事务，一定要注意手动回滚事务。

6、finally块必须对资源对象、流对象进行关闭，有异常也要做try-catch。

7、不要在finally块中使用return。

8、捕获异常与抛异常，必须是完全匹配，或者捕获异常是抛异常的父类。
说明：如果预期对方抛的是绣球，实际接到的是铅球，就会产生意外情况。

9、方法的返回值可以为null，不强制返回空集合，或者空对象等，必须添加注释充分
说明什么情况下会返回null值。

 

（十一）日志规约

1、应用中不可直接使用日志系统（Log4j、Logback）中的API，而应依赖使用日志框架SLF4J中的API，使用门面模式的日志框架，有利于维护和各个类的日志处理方式统一。

2、日志文件推荐至少保存15天，因为有些异常具备以“周”为频次发生的特点。

3、应用中的扩展日志（如打点、临时监控、访问日志等）命名方式：appName_logType_logName.log。logType:日志类型，推荐分类有stats/monitor/visit等；logName:日志描述。这种命名的好处：通过文件名就可知道日志文件属于什么应用，什么类型，什么目的，也有利于归类查找。

4、对trace/debug/info级别的日志输出，必须使用条件输出形式或者使用占位符的方式。

5、避免重复打印日志，浪费磁盘空间，务必在log4j.xml中设置additivity=false。

6、异常信息应该包括两类信息：案发现场信息和异常堆栈信息。如果不处理，那么通过关键字throws往上抛出。

 

（十二）其他

1、在使用正则表达式时，利用好其预编译功能，可以有效加快正则匹配速度。

2、velocity调用POJO类的属性时，建议直接使用属性名取值即可，模板引擎会自动按规范调用POJO的getXxx()，如果是boolean基本数据类型变量。

3、后台输送给页面的变量必须加$!{var}——中间的感叹号。

4、注意 Math.random() 这个方法返回是double类型，注意取值的范围 0≤x<1（能够取到零值，注意除零异常），如果想获取整数类型的随机数，不要将x放大10的若干倍然后取整，直接使用Random对象的nextInt或者nextLong方法。

5、获取当前毫秒数应当使用:

　　System.currentTimeMillis();

6、不要在视图模板中加入任何复杂的逻辑。

7、任何数据结构的构造或初始化，都应指定大小，避免数据结构无限增长吃光内存。

8、及时清理不再使用的代码段或配置信息。

 

（十三）单元测试

1、好的单元测试必须遵守AIR原则。

【说明】：单元测试在线上运行时，感觉像空气（AIR）一样并不存在，但在测试质量的保障上，却是非常关键的。好的单元测试宏观上来说，具有自动化、独立性、可重复执行的特点。

• A：Automatic（自动化）
• I：Independent（独立性）
• R：Repeatable（可重复）

2、单元测试应该是全自动执行的，并且非交互式的。测试用例通常是被定期执行的，执行过程必须完全自动化才有意义。输出结果需要人工检查的测试不是一个好的单元测试。单元测试中不准使用System.out来进行人肉验证，必须使用assert来验证。

3、保持单元测试的独立性。为了保证单元测试稳定可靠且便于维护，单元测试用例之间决不能互相调用，也不能依赖执行的先后次序。

4、单元测试是可以重复执行的，不能受到外界环境的影响。

5、对于单元测试，要保证测试粒度足够小，有助于精确定位问题。单测粒度至多是类级别，一般是方法级别。

6、核心业务、核心应用、核心模块的增量代码确保单元测试通过。

7、单元测试代码必须写在如下工程目录：src/test/java，不允许写在业务代码目录下。

8、单元测试的基本目标：语句覆盖率达到70%；核心模块的语句覆盖率和分支覆盖率都要达到100%

 

（十四）安全规约

1、隶属于用户个人的页面或者功能必须进行权限控制校验。

2、用户敏感数据禁止直接展示，必须对展示数据进行脱敏。

【说明】：个人手机号码显示为:138**9119，隐藏中间4位，防止隐私泄露。

3、用户输入的SQL参数严格使用参数绑定或者METADATA字段值限定，防止SQL注入，禁止字符串拼接SQL访问数据库。

4、用户请求传入的任何参数必须做有效性验证。

5、禁止向HTML页面输出未经安全过滤或未正确转义的用户数据。

6、表单、AJAX提交必须执行CSRF安全过滤。

7、在使用平台资源，譬如短信、邮件、电话、下单、支付，必须实现正确的防重放限制，如数量限制、疲劳度控制、验证码校验，避免被滥刷导致资损。

8、发贴、评论、发送即时消息等用户生成内容的场景必须实现防刷、文本内容违禁词过滤等风控策略。