Java编程规范

2019-10-15 本文已影响0人道貌岸然的鬼

本规范取自《码出高效—— 阿里巴巴 Java 开发手册 1.4.0》第一章，略有删减。

一、命名规范

代码中的命名均不能以下划线或美元符号开始，也不能以下划线或美元符号结束。
代码中的命名严禁使用拼音与英文混合的方式，更不允许直接使用中文的方式。

说明：正确的英文拼写和语法可以让阅读者易于理解，避免歧义。注意，即使纯拼音命名方式也要避免采用。
```
正例：alibaba / taobao / youku / hangzhou 等国际通用的名称，可视同英文。 反例：DaZhePromotion [打折] / getPingfenByName() [评分] / int 某变量 = 3 
```

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

正例：MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion 
反例：macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion

方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格，必须遵从驼峰形式。
```
正例： localValue / getHttpMessage() / inputUserId 
```
常量命名全部大写，单词间用下划线隔开，力求语义表达完整清楚，不要嫌名字长。
```
正例：MAX_STOCK_COUNT 
反例：MAX_COUNT
```
抽象类命名使用 Abstract 或 Base 开头；异常类命名使用 Exception 结尾；测试类命名以它要测试的类的名称开始，以 Test 结尾。

类型与中括号紧挨相连来表示数组。

正例：定义整形数组 int[] arrayDemo; 
反例：在 main 参数中，使用 String args[]来定义。

包名统一使用小写，点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式，但是类名如果有复数含义，类名可以使用复数形式。
```
正例：应用工具类包名为 com.alibaba.ai.util、类名为 MessageUtils（此规则参考 spring 的框架结构） 
```

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

反例：AbstractClass“缩写”命名成 AbsClass；condition“缩写”命名成 condi，此类随 意缩写严重降低了代码的可阅读性。

为了达到代码自解释的目标，任何自定义编程元素在命名时，使用尽量完整的单词组合来表达其意。

正例：在 JDK 中，表达原子更新的类名为：AtomicReferenceFieldUpdater。 
反例：变量 int a 的随意命名方式

各层命名规约：

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。

二、常量定义

不允许任何魔法值（即未经预先定义的常量）直接出现在代码中。
```
 反例：String key = "Id#taobao_" + tradeId;
     cache.put(key, value); 
```
在 long 或者 Long 赋值时，数值后使用大写的 L，不能是小写的 l，小写容易跟数字 1 混淆，造成误解。
```
说明：Long a = 2l; 写的是数字的 21，还是 Long 型的 2? 
```

不要使用一个常量类维护所有常量，要按常量功能进行归类，分开维护。

说明：大而全的常量类，杂乱无章，使用查找功能才能定位到修改的常量，不利于理解和维护。 
正例：缓存相关常量放在类 CacheConsts 下；系统配置相关常量放在类 ConfigConsts 下。

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

 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 定义。

三、代码格式

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

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

左小括号和字符之间不出现空格；同样，右小括号和字符之间也不出现空格；而左大括号前需要空格。详见第 5 条下方正例提示.
```
反例：if (空格 a == b 空格) 
```
if/for/while/switch/do 等保留字与括号之间都必须加空格。

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

说明：运算符包括赋值运算符=、逻辑运算符&&、加减乘除符号等。

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

说明：如果使用 tab 缩进，必须设置 1 个 tab 为 4 个空格。IDEA 设置 tab 为 4 个空格时，请勿勾选 Use tab character；而在 eclipse 中，必须勾选 insert spaces for tabs。

正例：
public static void main(String[] args) {      
 
 // 缩进 4 个空格      
    String say = "hello";
 // 运算符的左右必须有一个空格      
    int flag = 0;     
 // 关键词 if 与括号之间必须有一个空格，括号内的 f 与左括号，0 与右括号不需要空格      
    if (flag == 0) {          
        System.out.println(say);      
    }               
 // 左大括号前加空格且不换行；左大括号后换行      
    if (flag == 1) {          
        System.out.println("world");      
        // 右大括号前换行，右大括号后有 else，不用换行      
    } else {            
        System.out.println("ok");      
        // 在右大括号后直接结束，则必须换行      
    }  
}

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

正例：  
 // 这是示例注释，请注意在双斜线之后有一个空格  
 String ygb = new String();

单行字符数限制不超过 120 个，超出需要换行，换行时遵循如下原则:

1） 第二行相对第一行缩进 4 个空格，从第三行开始，不再继续缩进，参考示例。  
2） 运算符与下文一起换行。  
3） 方法调用的点符号与下文一起换行。  
4） 方法调用中的多个参数需要换行时，在逗号后进行。  
5） 在括号前不要换行，见反例。

正例： 
 StringBuffer sb = new StringBuffer();  
// 超过 120 个字符的情况下，换行缩进 4 个空格，点号和方法名称一起换行         sb.append("zi").append("xin")...    
     .append("huang")...
     .append("huang")... 
     .append("huang");  
反例： 
 StringBuffer sb = new StringBuffer();  
// 超过 120 个字符的情况下，不要在括号前换行                               sb.append("zi").append("xin")...append     
     ("huang");   
 
// 参数很多的方法调用可能超过 120 个字符，不要在逗号前换行  
 method(args1, args2, args3, ...      
     , argsX);

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

正例：下例中实参的 args1，后边必须要有一个空格。 
 method(args1, args2, args3);

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

单个方法的总行数不超过 80 行。

说明：包括方法签名、结束右大括号、方法内代码、注释、空行、回车及任何不可见字符的总 行数不超过 80 行。 
正例：代码逻辑分清红花和绿叶，个性和共性，绿叶逻辑单独出来成为额外方法，使主干代码 更加清晰；共性逻辑抽取成为共性方法，便于复用和维护。

没有必要增加若干空格来使某一行的字符与上一行对应位置的字符对齐。

正例： 
    int one = 1;
    long two = 2L;  
    float three = 3F;
    StringBuffer sb = new StringBuffer();  
说明：增加 sb 这个变量，如果需要对齐，则给 a、b、c 都要增加几个空格，在变量比较多的 情况下，是非常累赘的事情。

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

说明：任何情形，没有必要插入多个空行进行隔开。

四、OOP规约

OOP ——面向对象程序设计(Object Oriented Programming)

避免通过一个类的对象引用访问此类的静态变量或静态方法，无谓增加编译器解析成本，直接用类名来访问即可
所有的覆写方法，必须加@Override 注解。

说明：getObject()与 get0bject()的问题。一个是字母的 O，一个是数字的 0，加@Override 可以准确判断是否覆盖成功。另外，如果在抽象类中对方法签名进行修改，其实现类会马上编译报错。
相同参数类型，相同业务含义，才可以使用 Java 的可变参数，避免使用 Object。

  说明：可变参数必须放置在参数列表的最后。（提倡同学们尽量不用可变参数编程） 
   正例：public List<User> listUsers(String type, Long... ids) {...}

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

   说明：java.net.URLDecoder 中的方法 decode(String encodeStr) 这个方法已经过时，应该使用双参数 decode(String source, String encode)。接口提供方既然明确是过时接口， 那么有义务同时提供新的接口；作为调用方来说，有义务去考证过时方法的新实现是什么。

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

正例："test".equals(object); 
反例：object.equals("test"); 
说明：推荐使用 java.util.Objects#equals（JDK7 引入的工具类）

所有的相同类型的包装类对象之间值的比较，全部使用 equals 方法比较。
说明：对于 Integer var = ? 在-128 至 127 范围内的赋值，Integer 对象是在 IntegerCache.cache 产生，会复用已有对象，这个区间内的 Integer 值可以直接使用==进行判断，但是这个区间之外的所有数据，都会在堆上产生，并不会复用已有对象，这是一个大坑，推荐使用 equals 方法进行判断。

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

 1） 【强制】所有的 POJO 类属性必须使用包装数据类型。  
 2） 【强制】RPC 方法的返回值和参数必须使用包装数据类型。  
 3） 【推荐】所有的局部变量使用基本数据类型。  
 说明：POJO 类属性没有初值是提醒使用者在需要使用时，必须自己显式地进行赋值，任何 NPE 问题，或者入库检查，都由使用者来保证。

正例：数据库的查询结果可能是 null，因为自动拆箱，用基本数据类型接收有 NPE 风险。  
反例：比如显示成交总额涨跌情况，即正负 x%，x 为基本数据类型，调用的 RPC 服务，调用 不成功时，返回的是默认值，页面显示为 0%，这是不合理的，应该显示成中划线。所以包装 数据类型的 null 值，能够表示额外的信息，如：远程调用失败，异常退出。

构造方法里面禁止加入任何业务逻辑，如果有初始化逻辑，请放在 init 方法中。
使用索引访问用 String 的 split 方法得到的数组时，需做最后一个分隔符后有无内容的检查，否则会有抛 IndexOutOfBoundsException 的风险。
```
说明： 
    String str = "a,b,c,,";  
    String[] ary = str.split(",");  
    // 预期大于 3，结果是 3 
    System.out.println(ary.length);
```
当一个类有多个构造方法，或者多个同名方法，这些方法应该按顺序放置在一起，便于阅读.

类内方法定义的顺序依次是：公有方法或保护方法 > 私有方法 > getter/setter 方法。

说明：公有方法是类的调用者和维护者最关心的方法，首屏展示最好；保护方法虽然只是子类关心，也可能是“模板设计模式”下的核心方法；而私有方法外部一般不需要特别关心，是一个黑盒实现；因为承载的信息价值较低，所有 Service 和 DAO 的 getter/setter 方法放在类体最后。
setter 方法中，参数名称与类成员变量名称一致，this.成员名 = 参数名。在 getter/setter 方法中，不要增加业务逻辑，增加排查问题的难度。
```
反例： 
   public Integer getData() {      
    if (condition) {  
        return this.data + 100;  
    } else { 
        return this.data - 100; 
    }  
}
```

循环体内，字符串的连接方式，使用 StringBuilder 的 append 方法进行扩展。

说明：下例中，反编译出的字节码文件显示每次循环都会 new 出一个 StringBuilder 对象， 然后进行 append 操作，最后通过 toString 方法返回 String 对象，造成内存资源浪费。 
反例： 
    String str = "start";      
    for (int i = 0; i < 100; i++) {          
        str = str + "hello";      
    }

final 可以声明类、成员变量、方法、以及本地变量，下列情况使用 final 关键字。

 1） 不允许被继承的类，如：String 类。  
 2） 不允许修改引用的域对象。  
 3） 不允许被重写的方法，如：POJO 类的 setter 方法。
 4） 不允许运行过程中重新赋值的局部变量。  
 5） 避免上下文重复使用一个变量，使用 final 描述可以强制重新定义一个变量，方便更好 地进行重构.

慎用 Object 的 clone 方法来拷贝对象。

说明：对象的 clone 方法默认是浅拷贝，若想实现深拷贝需要重写 clone 方法实现域对象的深度遍历式拷贝。

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

1） 如果不允许外部直接通过 new 来创建对象，那么构造方法必须是 private。  
2） 工具类不允许有 public 或 default 构造方法。  
3） 类非 static 成员变量并且与子类共享，必须是 protected。   
4） 类非 static 成员变量并且仅在本类使用，必须是 private。  
5） 类 static 成员变量如果仅在本类使用，必须是 private。  
6） 若是 static 成员变量，考虑是否为 final。  
7） 类成员方法只供类内部调用，必须是 private。   
8） 类成员方法只对继承类公开，那么限制为 protected。 
说明：任何类、方法、参数、变量，严控访问范围。过于宽泛的访问范围，不利于模块解耦。 思考：如果是一个 private 的方法，想删除就删除，可是一个 public 的 service 成员方法或
成员变量，删除一下，不得手心冒点汗吗？变量像自己的小孩，尽量在自己的视线内，变量作 用域太大，无限制的到处跑，那么你会担心的。

五、控制语句

在一个 switch 块内，每个 case 要么通过 break/return 等来终止，要么注释说明程序将继续执行到哪一个 case 为止；在一个 switch 块内，都必须包含一个 default 语句并且放在最后，即使空代码。
在 if/else/for/while/do 语句中必须使用大括号。即使只有一行代码，避免采用单行的编码方式：if (condition) statements;

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

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

表达异常的分支时，少用 if-else 方式，这种方式可以改写成：

if (condition) {              
    ...             
    return obj;    
}   // 接着写 else 的业务逻辑代码;  
说明：如果非得使用 if()...else if()...else...方式表达逻辑，避免后续代码维 护困难，请勿超过 3 层。  
正例：超过 3 层的 if-else 的逻辑判断代码可以使用卫语句、策略模式、状态模式等来实现， 其中卫语句示例如下： 
 public void today() {      
     if (isBusy()) {   
            System.out.println(“change time.”);            
            return;      
        } 
 
         if (isFree()) {  
             System.out.println(“go to travel.”);                            
            return;     
        } 
 
     System.out.println(“stay at home to learn Alibaba Java Coding Guidelines.”);                return; 
 }

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

说明：很多 if 语句内的逻辑相当复杂，阅读者需要分析条件表达式的最终结果，才能明确什么 样的条件执行什么样的语句，那么，如果阅读者分析逻辑表达式错误呢？ 
正例： 
    // 伪代码如下 
    final boolean existed = (file.open(fileName, "w") != null) && (...) || (...); 
 if (existed) {     
        ... 
    }   
反例： 
    if ((file.open(fileName, "w") != null) && (...) || (...)) {     
        ... 
    }

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

避免采用取反逻辑运算符。

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

六、注释规约

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

说明：在 IDE 编辑窗口中，Javadoc 方式会提示相关注释，生成 Javadoc 可以正确输出相应注 释；在 IDE 中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高 阅读效率。

所有的抽象方法（包括接口中的方法）必须要用 Javadoc 注释、除了返回值、参数、异常说明外，还必须指出该方法做什么事情，实现什么功能。
```
说明：对子类的实现要求，或者调用注意事项，请一并说明。 
```
所有的类都必须添加创建者和创建日期。
方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。
所有的枚举类型字段必须要有注释，说明每个数据项的用途。
与其“半吊子”英文来注释，不如用中文注释把问题说清楚。专有名词与关键字保持英文原文即可。

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

说明：代码与注释更新不同步，就像路网与导航软件更新不同步一样，如果导航软件严重滞后， 就失去了导航的意义。

谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果无用，则删除。

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

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

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

反例： 
// put elephant into fridge  
    put(elephant, fridge);      
方法名 put，加上两个有意义的变量名 elephant 和 fridge，已经说明了这是在干什么，语 义清晰的代码不需要额外的注释。

特殊注释标记，请注明标记人与标记时间。注意及时处理这些标记，通过标记扫描，经常清理此类标记。线上故障有时候就是来源于这些标记处的代码。

 1） 待办事宜（TODO）:（ 标记人，标记时间，[预计处理时间]）    
    表示需要实现，但目前还未实现的功能。这实际上是一个 Javadoc 的标签，目前的 Javadoc 还没有实现，但已经被广泛使用。只能应用于类，接口和方法（因为它是一个 Javadoc 标签）。  
 2） 错误，不能工作（FIXME）:（标记人，标记时间，[预计处理时间]）    
    在注释中用 FIXME 标记某代码是错误的，而且不能工作，需要及时纠正的情况。

七、其他

在使用正则表达式时，利用好其预编译功能，可以有效加快正则匹配速度。
```
说明：不要在方法体内定义：Pattern pattern = Pattern.compile(“规则”); 
```

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

说明：如果 var 等于 null 或者不存在，那么${var}会直接显示在页面上。

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

获取当前毫秒数 System.currentTimeMillis(); 而不是 new Date().getTime();

说明：如果想获取更加精确的纳秒级时间值，使用 System.nanoTime()的方式。在 JDK8 中， 针对统计时间等场景，推荐使用 Instant 类。

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

说明：根据 MVC 理论，视图的职责是展示，不要抢模型和控制器的活。

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

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

说明：对于垃圾代码或过时配置，坚决清理干净，避免程序过度臃肿，代码冗余。 
正例：对于暂时被注释掉，后续可能恢复使用的代码片断，在注释代码上方，统一规定使用三 个斜杠(///)来说明注释掉代码的理由