Java编码规范

Java编码规范

---

前言

使Java编码便于维护，提高系统安全性和性能

---

1. 命名规范

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

1.2 代码中严禁使用中英文混合的方式，不允许使用中文的方式。
说明：正确的英文拼写和违法可以让阅读者易于理解，避免歧义，不建议使用纯拼音命名方式命名。

1.3 类名使用UpperCamelCase风格，必须遵从驼峰形式，但以下情形例外：（领域模型的相关命名，如DO/BO/DTO/VO等）

1.4 方法名、参数名、成员变量、局部变量都统一使用LowerCamelCase风格，应遵从驼峰形式。

1.5 常量命名全部大写，单词间用下划线隔开，语义表达完整清楚，不要嫌名字长。

1.6 抽象类命名使用Abstract开头，异常类命名使用Exception结尾，测试类命名以它要测试的类名拼Test结尾。

1.7 POJO类中布尔类型的变量都不允许加is，否则部分框架解析会引起序列化错误。

1.8 包名统一使用小写，分隔符之间有且仅有一个自然语义的英语单词，包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式。
示例：应用工具类包名为com.alibaba.open.util，类名为MessageUtils

1.9 杜绝完全不规范的缩写，避免望文不知义，随意缩写严重降低了代码的可阅读性

1.10 如果使用设计模式，建议在类名中体现出具体模式。
示例：public class OrderFactory

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

1.12 接口和实现类的命名规则
对于Service和Dao类，暴漏出来的服务一定是借口，内部实现类用Impl的后缀与接口区别。

1.13 枚举类名建议带上Enum后缀，枚举成员名称需要全大写，单词间用下划线隔开。
说明：枚举其实就是特殊的常量类，且构造方法被默认强制是私有。

1.14 避免在子父类的成员变量之间、或者不同代码块的局部变量之间采用完全相同的命名，使可读性降低。
说明：子类和父类成员变量名相同，即使是public类型的变量也能够通过编译，而局部变量在同一方法内的不同代码块中同名也是合法的，但是要避免使用。对于非setter/getter的参数名称也要避免与成员变量名称相同

1.15 各层命名规则

• Service/DAO层方法命名规则
  • 获取单个对象的方法用get做前缀
  • 获取多个对象的方法用list做前缀
  • 获取统计值的方法用count做前缀
  • 插入方法用save或insert做前缀
  • 删除方法用remove或delete做前缀
  • 修改方法用update做前缀
• 领域模型命名规则
  • 数据对象：xxxDO，xxx即为数据表名。
  • 数据传输对象：xxxDTO，xxx为业务领域相关的名称
  • 展示对象：xxxVO，xxx一般为网页名称
  • POJO使DO/DTO/BO/VO的统称，禁止命名成xxxPOJO

1.16 源文件以其最顶层的类名来命名，大小写敏感，文件扩展名为.java

1.17 源文件编码格式统一为无BOM的UTF-8

1.18 除了行结束符序列，ASCII水平空格字符（0x20，即空格）是源文件中唯一允许出现的空白字符
说明：所有其他字符串中的空白字符都要进行转义；制表符不用于缩进。采用4个空格缩进，禁止使用tab字符。如果使用tab缩进，必须设置1个tab为4个空格。IDEA设置tab为4个空格，请勿勾选Use tab character；

2. 常量定义

2.1 不允许出现任何魔法值（即未经定义的常量）直接出现在代码中，也表示移除硬编码。

2.2 long或Long赋初始值时，必须使用大写的L，不能是小写的l，容易同数字1混淆。

2.3 不要使用一个常量类维护所有常量，应该按常量功能进行归类，分开维护。
说明：大而全的常量类只有使用查找功能才能定位到修改的常量，不利于理解和维护

2.4 常量的复用层次有5层：跨应用共享，应用内共享，子工程内共享，包内共享，类内共享。

• 跨应用共享：放置在中央仓库中，通常在引包的constant目录下
• 应用内共享：放置在项目的modules中的constant目录下，易懂的变量统一定义成应用内共享变量，便于复用
• 子工程内共享：即在当前子工程的constant目录下
• 包内共享：即在当前包下单独的constant目录下
• 类内共享：直接在类内部private static final定义

2.5 如果变量值仅在一个范围内变化用Enum类，如果还带有名称之外的延伸属性，必须使用Enum类，下面正例中的数字就是延伸信息，表示星期几。

3. 格式规则

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

• 左大括号前不换行
• 左大括号后换行
• 右大括号前换行
• 右大括号后还有else等代码则不换行
• 表示终止右大括号后必须换行

3.2 左括号和后一个字符之间不出现空格；同样右括号和前一个字符之间也不出现空格。

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

3.4 任何运算符左右必须加一个空格
说明：运算符包括赋值运算符、逻辑运算符、加减乘除、三目运算符

3.5 缩进采用4个空格，禁止使用tab字符

3.6 单行字符数限制不超过120个，超出需要换行，换行时遵循以下规则

• 第二行相对第一行缩进4个空格，从第三行开始，不再继续缩进，参考示例。
• 运算符与下文一起换行
• 方法调用的点符号与下文一起换行
• 在多个参数超长，逗号后进行换行
• 在括号前不要换行

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

3.8 IDEA的text file encoding设置为UTF-8，IDEA中文件的换行符使用UNIX格式，不要使用windows格式。

3.9 没有必要增加若干空格使某一行的字符和上一行的相应字符对齐。

3.10 方法体内的执行语句组、变量语句组、不同业务逻辑之间或不同语义之间插入一个空格，相同业务逻辑和相同语义之间不需要插入空格。

3.11 当某行语句在逻辑上比下面语句高一个层次时，该行下面的语句都需要在该行的基础上缩进一个单位。

3.12 复合语句中的语句要比复合语句缩进一个层次。

3.13 方法名和其参数列表左侧括号之间不能有空格。

3.14 一元操作符和操作数之间不能有空格，如负数，自增，自减。

3.15 在进行类型强制转换时，右侧括号和转换值之间不需要空格隔开。

3.16 注释的双斜线和注释内容之间需要使用一个空格隔开。

// 注释内容

3.17 二目和三目运算符左右两侧都需要添加一个空格。

3.18 左右小括号与字符间不需要存在空格，左大括号前需要空格。

if(a=b) {}

3.19 左大括号位于声明语句的末尾，并与末尾之间留有一个空格。

3.20 右大括号换行，并同相应的声明语句对齐。

3.21 方法与方法之间需要空白行分隔。

3.22 复合语句的左大括号应位于复合语句起始行行尾，并添加一个空格，右大括号需要换行并与复合语句首行对齐。

4. OOP规则

4.1 避免通过一个类型的对象来引用此类的静态方法和静态成员，直接使用类名访问即可，减少编译器解析成本。

4.2 所有覆写方法都必须加@Override注释。

4.3 具有相同业务含义，相同参数类型才可以使用java的可变参数，避免使用Object。
说明：可变参数必须放置在参数列表最后（提倡尽量不使用可变参数编程）

示例：public void test(String name, Integer... ids) {}

4.4 外部已经调用或组件库已经依赖的接口，不允许修改方法签名，避免对调用方产生影响，接口过时弃用时必须添加@Deprecated注解，并说明新的服务和新的接口。

4.5 不能使用过时的类和方法。调用方在调用新的方法时，需要对依据旧方法对新的方法进行考证。

4.6 Object的equals方法容易出现空指针异常，必须遵守常量或确定值调用equals方法。

4.7 所有相同类型的包装类必须使用equals进行比较。
说明：Integer在-128～127上的值都在IntegerCache cache产生，会复用已有对象，可以使用 == 判断值是否一致，超出区间范围的值会从堆上产生，不会复用已存在的对象，栈地址指向不一致，需要使用equals方法进行值判断

4.8 基本数据类型和报数据类型的使用标准规则：

• 所有的POJO类需要使用包装的数据类型
• RPC返回值和参数必须使用包装数据类型
• 所有的局部变量都使用基本数据类型

说明：POJO类没有赋初始值是提醒使用者需要显示的赋初始值，任何空指针问题或者入库检查由使用者保证。
正例：数据库的查询结果可能是null，因为自动拆箱，同基本数据类型接收由空指针风险。
反例：比如现实成交总额涨跌情况，即正负x%，x为基本数据类型，调用RPC服务，调用不成功时，返回的是默认值，页面显示：0%，这个是不合理的，应该显示成中划线。所以包装数据类型的null值，能够显示表示额外的信息，如远程调用失败，异常退出。

4.9 定义DO/DTO/VO等POJO类时，不要设定任何属性默认值。
反例：POJO类的gmtCreate默认值为newDate()，但是这个属性在数据提取时并没有入具体值，在更新其他字段时又附带更新了此字段，导致创建时间别修改成当前时间。

4.10 序列化类新增属性时，请不要修改serialVersionUID字段，避免反序列化失败，如果完全不兼容升级，避免反序列化混乱，那么请修改serialVersionUID值。
说明：注意serialVersionUID不一致会抛出序列化运行时异常。

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

4.12 POJO类必须是toString方法。使用IDE中的工具：source > generate toString时，如果继承了另一个POJO类，注意在前面加一下super.toString。
说明：在方法执行抛出异常时，可以直接调用POJO的toString()方法打印其属性值，便于排查问题。

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

4.14 当一个类有多个构造方法，或者多个同名方法，这些方法应该按顺序放置在一起，便于阅读。

4.15 类内方法定义顺序依次是：公有方法或保护方法>私有方法>getter/setter方法。
说明：公有方法是类的调用者和维护者最关心的方法，首屏展示最好：保护方法虽然只是子类关心，也可能是“模版设计模式”下的核心方法；而私有方法内部一般不需要特别关系，是一个黑盒实现；因为方法信息价值较低，所有service和dao的getter/setter方法一般放到最后。

4.16 setter方法中，参数名称与类成员变量名称一致，this.成员名-参数名，在getter/setter方法中，尽量不要增加业务逻辑，增加排查问题的难度。

4.17 循环内，字符串的连接方式，使用StringBuilder的append方法进行扩展。
说明：反编译出的字节码文件显示每次循环都会new出一个StringBuilder的对象，然后进行append操作，最后通过toString方法退回String对象，造成内存资源浪费。

4.18 下列情况，声明成final会更有提示性：

• 不需要重新赋值的变量，包括类属性、局部变量。
• 对象参数前加final，表示不允许修改引用的指向。
• 类方法确定不允许被重写。

4.19 慎用Object的clone方法来拷贝对象。
说明：对象的clone方法默认是浅拷贝，若想实现深拷贝需要重写clone方法实现属性对象的拷贝。

4.20 类成员与方法访问控制从严：

• 如果不允许外部直接通过new来创建对象，那么构造方法必须是private。
• 工具类不允许有public或default构造方法。
• 类非static成员变量并且与子类共享，必须是protected。
• 类非static成员变量并且仅在本类使用，必须是private。
• 类static成员变量如果仅在本类使用，必须是private。
• 若是static成员变量，必须考虑是否为final。
• 类成员方法之供类内部调用，必须是private。
• 类成员方法只对继承类公开，那么限制为protected。

说明：任何类、方法、参数、变量严控访问范围。过宽泛的访问范围，不利于模块解耦。

4.21 数据类型转换中字符串转整型常用的是Integer.valueOf与Integer.parseInt，其中第一个返回的是对象，对于基本数据类型进行了装箱，第二个是返回基本数据类型，使用二者时需要根据具体需求合理选择。

4.22 浮点数之间的等值判断，基本数据类型不能用==来比较，包装数据类型不能用equals来判断。
说明：浮点数之间的等值判断采用“尾数+阶码”的编码方式，类似于科学计数法的“有效数字+指数”的表示方法。二进制无法精确表示大部分的十进制小数。

4.23 为了防止精度损失，禁止使用的构造方法BigDecimal(double)的方式把double值转化为BigDecimal对象。
说明：BigDecimal(double)存在精度损失风险，在精确计算或值比较的场景中可能会导致业务逻辑异常。

5. 集合处理

5.1 关于hashCode和equals的处理，遵循如下规则：

• 只要重写equals，就必须重写hashCode。
• 因为Set存储的是不重复的对象，依据hashCode和equals进行判断，所以Set存储的对象必须重写这两个方法。
• 如果自定义对象作为Map的链，那么必须重写hashCode和equals.。

说明：String重写了hashCode和equals方法，所以我们可以非常愉快地使用String对象作为key使用。

5.2 ArrayList的subList结果不可强转成ArrayList，否则会抛出ClassCaseException异常：java.util.RandomAccessSublist cannnot be case to java.util.ArrayList
说明：subList返回的是ArrayList的内部类SubList，并不是ArrayList，而是ArrayList的一个视图，对于SubList子列表的所有操作最终会反映到原列表上。

5.3 在sublist场景中，高度注意对原集合元素个数的修改，会导致子列表的遍历、增加、删除均产生ConcurrentMOdificationException异常。

5.4 使用集合转数组的方法，必须使用集合的toArray(T[] array)，传入的是类型完全一样的数组，大小就是list.size()。
说明：使用toArray带参数方法，入参分配的数组空间不够大时，toArray方法内部将重新分配内存空间，并返回新数组地址；如果数组元素大于实际所需，下标为[list.size()]的数组元素将被置为null，其他数组元素保持原值，因此最好将方法入参数组大小定义与集合元素个数一致。

5.5 使用工具类Arrays。asList()把数组转换成集合时，不能使用其修改集合相关的方法，它的add/remove/clear方法会抛出UnsupportedOperationException异常。

5.6 不要在foreach循环里进行元素的remove/add操作。remove元素请使用Iterator方式，如果并发操作，需要对Iterator对象加锁。

5.7 在JDK7版本及以上，Comparator要满足如下三个条件，不然Arrays.sort，Collections.sort会报IllegalArgumentException异常。
说明：

• x，y比较结果和y，x的比较结果相反
• x>y，y>z，则x>z
• x=y，则x，z比较结果和y，z比较结果相同

5.8 集合初始化时，尽量指定集合初始值大小。
说明：ArrayList尽量使用ArrayList(intinitialCapacity)初始化。

5.9 使用entrySet遍历Map类集合KV，而不是keySet方式进行遍历。使用Map的方法keySet()/values()/entrySet()返回集合对象时，不可以对其进行添加元素操作，否则会抛出UnsupportedOperationException异常。
说明：keySet其实是遍历了2次，一次是转为Iterator对象，另一次是从hashMap中取出key所对应的value。而entrySet只是遍历了一次就把key和value都放到了entry中，效率更高。如果是JDK8，使用Map.foreach方法。
正例：values()返回的是V值集合，是一个list集合对象；keySet()返回的是K值集合，是一个Set集合对象；entrySet()返回的是K-V值组合集合。

5.10 关注Map类集合K/V能不能存储null值的情况
反例：由于HashMap的干扰，很多人认为ConcurrentHashMap是可以置入null值，注意存储null值时会抛出空指针异常。

5.11 合理利用好集合的有序性(sort)和稳定性(order)，避免集合的无序性(unsort)和不稳定性(unorder)带来的负面影响。
说明：有序性是指遍历的结果是按某种比较规则依次排列的，稳定性指集合每次遍历的元素次序是一定的。如：ArrayList是order/unsort；HashMap是unorder/unsort;TreeSet是order/sort。

5.12 利用Set元素唯一的特性，可以快速对一个集合进行去重操作，避免使用List的contain方法进行遍历，对比，去重操作。

5.13 空判断推荐使用StringUtils.isEmpty或StringUtils.isBlank方法，对于高频判空的业务代码，可以考虑提取公共的工具类方法。
Collections类返回的对象，如：emptyList()/singletonList()等都是immutablelist，不可对其进行添加或者删除元素的操作。
反例：如果查询无结果，返回Collections.emptyList()空集合对象，调用方一旦进行了添加元素的操作，就会出发Unsupported Operation Exception异常。

5.14 在subList场景中，高度注意对原集合元素的增加或删除，俊辉导致子列表的遍历，增加，删除产生Concurrent Modification Exception异常。

5.15 泛型通配符<? extends T>来接收返回的数据，次写法的泛型集合不能使用add方法，而<? extends T>不能使用get方法，作为接口调用赋值时易出错。
说明：扩展说一下PECS(Producer Extends Consumer Super)原则：第一，频繁往外读取内容的，适合用<? extends T>。第二，经常往里插入的，使用<? super T>

5.16 在无泛型限制定义的集合赋值给泛型限制的集合时，在使用集合元素时，需要进行instanceof判断，避免抛出ClassCastException异常。
说明：泛型是在JDK5后才出现，考虑到向前兼容，编译器是允许非泛型集合与泛型集合互相赋值。

6. 并发处理

6.1 获取单例对象需要保证线程安全（常用双循环检查锁），其中的方法也要保证线程安全。
说明：资源驱动类、工具类、单例工厂类都需要注意。

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

6.3 线程资源必须通过线程池提供，不允许在应用中自行显式创建线程。
说明：使用线程池的好处是减少在创建和销毁线程上所花的时间以及系统资源的开销，解决资源不足的问题。如果不使用线程池，有可能造成系统创建大量同类线程而导致消耗完内存或者“过去切换”的问题。

6.4 线程池不允许使用Executors去创建，而是通过Thread Pool Executor的方式，这样的处理方式方便维护时更加明确线程池的运行规则，规避资源耗尽的风险。
说明：Executors返回的线程池对象的弊端如下：

• FixedThreadPool 和 SingleThreadPool允许的请求队列为Integer.MAX_VALUE，可能会堆积大量的请求，从而导致内存溢出。
• CachedThreadPool和ScheduledThreadPool允许的创建线程数量为Integer.MAX_VALUE，可能会堆积大量的请求，从而导致内存溢出。

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

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

6.7 对多个资源，数据库表，对象同时加锁时，需要保持一致的加锁顺序，否则可能会造成死锁。
说明：线程1需要对表A、B、C依次全部加锁后才可以进行更新操作，那么线程二的加锁顺序也必须是A、B、C，否则可能出现死锁。

6.8 并发修改同一记录时，避免更新丢失，需要加锁。要么在应用层加锁，要么在缓存加锁，要么在数据库层使用乐观锁，使用version作为更新依据。
说明：如果每次访问冲突概率小于20%，推荐使用乐观锁，否则使用悲观锁。乐观锁的重试次数不得小于3次。

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

6.10 使用CountDownLatch进行异步转同步操作，每个线程退出前必须调用countDown方法，线程执行代码注意catch异常，确保countDown方法可以执行，避免主线程无法执行至await方法，直到超过才返回结果。
说明：注意，子线程抛出异常堆栈，不能在主线程try-catch到。

6.11 避免Random实例被多线程使用，虽然共享该实例是线程安全的，但会因竞争同一seed导致的性能下降。
说明：Random实例包括java.util.Random的实例或者Math.random()实例。
正例：在JDK7之后，可以直接使用APIThreadLocalRandom，在JDK7之前，可以做到每个线程一个实例。

6.12 在并发场景下，通过双重检查锁（double-checkedlocking）实现延迟初始化的优化问题隐患（可参考The Double-CheckedLockingisBroken’ Declaration）,推荐问题解决方案中较为简单一种（适用于JDK5及以上版本），将目标属性声明为volatile型。

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

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

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

6.14 HashMap在容量不够进行resize时由于高并发可能出现死链，导致CPU飙升，在开发过程中注意规避此风险。

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

6.16 必须回收自定义的ThreadLocal变量，尤其在线程池场景下，线程经常会被复用，如果不清理自定义的ThreadLocal变量，可能只影响后续业务逻辑和造成内存泄漏等问题，尽量在代理中使用try-finally块进行回收。

6.17 在使用尝试机制来获取锁方式中，进入业务代码块之前，必须先判断当前线程是否持有锁。锁的释放规则与锁的阻塞等待方式相同。

7 控制语句

7.1 在一个switch块内，每个case要么通过break/return等来终止，要么注释说明程序将继续执行到哪一个case为止；在一个switch块内，都必须包含一个default语句并且放在最后，即使它什么代码也没有。当switch括号内的变量类型为String并且此变量为外部参数时，必须先进行null判断。

**7.2 在if/else/for/while/do语句中必须使用大括号，即使只有一行代码，避免使用下面的形式：if(condition) statements; **

7.3 推荐尽量少用else，if-else的方式可以改写成：

if(condition){
...
	return obj;
}
// 接着写else的业务逻辑代码

说明： 如果非得使用if()…else…方式表达逻辑，请勿超过3层，超过请使用状态设计模式。
正例：逻辑上超过3层的if-else代码可以使用卫语句，或者状态模式来实现。

7.4 除常用方法（如getXxx/isXxx）等外，不要在条件判断中执行其它复杂的语句，将复杂逻辑判断的结果赋值给一个有意义的布尔变量名，以提高可读性。
说明：很多if语句内的逻辑相当复杂，阅读者需要分析条件表达式的最终结果，才能明确什么样的条件执行什么样的语句，那么，如果阅读者分析逻辑表达式错误呢？

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

7.6 if、while等判断语句中的条件部分，应将常量写在左边，而把变量写在右边。

7.7 在高并发场景中，避免使用“等于”判断作为终端或者退出的条件。
说明：如果并发控制没有处理好，容易产生等值判断被“击穿”的情况，使用大于或者小于的区间判断靠肩来代替。
反例：判断剩余奖品数量等于0时，终止发放奖品，但因为并发处理错误导致奖品数量瞬间变成了负数，这样的话，活动无法终止。

7.8 避免采用取反逻辑运算符。
说明：取反逻辑不利于快速理解，并且取反逻辑写法必然存在对应的正向逻辑写法。
正例：使用if(x<6)来表达x小于6
反例：使用if(!(x>=6))来表达x小于6

8 注释规约

8.1 类、类属性、类方法的注释必须使用Javadoc规范，使用/**内容*/格式，不得使用//xxx方式。
说明：在IDEA编辑窗口中，Javadoc方式会提示相关注释，生成Javadoc可以正确输出相应注释，在IDEA中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。

8.2 所有的抽象方法（包括接口中的方法）必须要用Javadoc注释，除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。
说明：对子类的实现要求，或者调用注意事项，请一并说明。

8.3 所有的类都必须添加创建者信息。

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

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

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

8.7 代码修改的同时，注释也要进行相应的修改，尤其是参数，返回值，异常，核心逻辑等的修改。
说明：代码与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后就失去了导航的意义。

8.8 注释掉的代码尽量要配合说明，而不是简单的注释掉。
说明：代码被注释掉有两种可能性：1）后续会恢复此段代码逻辑。2）永久不用。前者如果没有备注信息，难以知晓注释动机。后者建议直接删掉（代码仓库保存了历史代码）。

8.9 对于注释的要求：第一，能够准确反应设计思想和代码逻辑；第二，能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路；注释也是给继任者看的，使其能够快速接替自己的工作。

8.10 好的命名，代码结构是自解释的，注释力求精简准确，表达到位。避免出现注释的一个极端：过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。

8.11 特殊注释标记，请注明标记人与标记时间，注意及时处理这些标记，通过标记扫描，经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。
1) 待办事宜（TODO）：（标记人，标记时间，[预计处理时间]）表示需要实现，但目前还未实现的功能。这实际上是一个Javadoc的标签，目前的Javadoc还没有实现，但已经被广泛使用。只能应用于类，接口和方法（因为它是一个Javadoc标签）。

2) 错误，不能工作（FIXME）：（标记人，标记时间，[预计处理时间]）在注释中用FIXME标记某代码是错误的，而且不能工作，需要及时纠正的情况。

9 校验规约

9.1 对参数进行必要的检验，如非空、合法性等；

9.2 在验证参数时建议使用断言或合适的工具；

9.3 尽量避免在方法内部进行大量校验；
方法中需要进行参数校验的场景：

• 调用频次低的方法。
• 执行时间开销很大的方法，参数校验时间几乎可以忽略不计，但如果因为参数错误导致中间执行回退，或者错误，那得不偿失。
• 需要极高稳定性和可用性的方法
• 对外提供的开发接口，不管是RPC/API/HTTP接口
• 敏感权限入口

方法中不需要参数校验的场景：

• 极有可能被循环调用的方法，不建议对参数进行校验。但在方法说明里必须注明外部参数检查要求。
• 底层的方法调用频度都比较高，一般不校验。毕竟是像纯净水过滤的最后一道，参数错误不太可能到底层才会暴漏问题。一般DAO层与Service层都在同一个应用中，部署在同一台服务器中，所以DAO的参数校验，可以省略。
• 被声明或private只会被自己代码所调用的方法，如果能够确定调用方法的代码传入参数已经做过检查或者肯定不会有问题，此时可以不校验参数。

10 异常处理

10.1 Java类库中定义的一类RuntimeException可以通过预先检查进行规避，而不应该通过catch来处理，比如：IndexOutOfBoundeException， NullPointerException等等。
说明：无法通过与检查的异常除外，如在解析一个外部传来的字符串形式数字时，通过catchNumberFormatException来实现。

10.2 异常不要用来做流程控制，条件控制，因为异常的处理效率比条件分支低。

10.3 对大段代码进行try-catch，这是不负责任的表现。catch时请分清稳定代码和非稳定代码，稳定代码指的是无论如何不会出错的代码。对于非稳定代码的catch尽可能进行区分异常类型，再做对应的异常处理。

TODO 待更新 2025-01-03