java编码规范

java编码规范精简版

一、编程规约

(一) 命名风格

  1. 【强制】代码中的命名均不能以下划线或美元符号开始,也不能以下划线或美元符号结束。

  2. 【强制】代码中的命名严禁使用拼音与英文混合的方式,更不允许直接使用中文的方式。

  3. 【强制】类名使用 UpperCamelCase 风格,但以下情形例外:DO / BO / DTO / VO / AO / PO / UID 等。

    正例:MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion

    反例:macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion

  4. 【强制】方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格,必须遵从驼峰形式。

    正例: localValue / getHttpMessage() / inputUserId

  5. 【强制】常量命名全部大写,单词间用下划线隔开,力求语义表达完整清楚,不要嫌名字长。正例:MAX_STOCK_COUNT

    反例:MAX_COUNT

  6. 【强制】抽象类命名使用 Abstract 或 Base 开头;异常类命名使用 Exception 结尾;测试类命名以它要测试的类的名称开始,以 Test 结尾。

  7. 【强制】类型与中括号紧挨相连来表示数组。正例:定义整形数组 int[] arrayDemo;

    反例:在 main 参数中,使用 String args[]来定义。

  8. 【强制】POJO 类中布尔类型的变量,都不要加 is 前缀,否则部分框架解析会引起序列化错误。boolean型get可以使用is代替(public boolean isMarsupial())

    反例:定义为基本数据类型 Boolean isDeleted 的属性,它的方法也是 isDeleted(),RPC框架在反向解析的时候,“误以为”对应的属性名称是 deleted,导致属性获取不到,进而抛出异常。

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

    正例:应用工具类包名为 com.alibaba.ai.util、类名为 MessageUtils(此规则参考 spring的框架结构)

  10. 【强制】杜绝完全不规范的缩写,避免望文不知义。

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

  11. 接口和实现类的命名有两套规则:

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

    正例:CacheServiceImpl 实现 CacheService 接口。
    

    2)【推荐】 如果是形容能力的接口名称,取对应的形容词为接口名(通常是–able 的形式)。

    正例:AbstractTranslator 实现 Translatable 接口。
    
  12. 【参考】枚举类名建议带上 Enum 后缀,枚举成员名称需要全大写,单词间用下划线隔开。

    说明:枚举其实就是特殊的类,域成员均为常量,且构造方法被默认强制是私有。

    正例:枚举名字为 ProcessStatusEnum 的成员名称:SUCCESS / UNKNOWN_REASON。

  13. 【参考】各层命名规约:

    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。
    

    C)Controller层

    1) 默认使用 save info list update remove
    
  14. 【强制】变量第一个单词避免使用一个字母、
    反例:eMail

(二) 常量定义

  1. 【强制】不允许任何魔法值(即未经预先定义的常量)直接出现在代码中。
    反例:

    1
    2
    String key = "Id#taobao_" + tradeId;
    cache.put(key, value);
  2. 【强制】在 long 或者 Long 赋值时,数值后使用大写的 L,不能是小写的 l,小写容易跟数字 1 混淆,造成误解。

    说明:Long a = 2l; 写的是数字的 21,还是 Long 型的 2L

(三) 代码格式

  1. 【强制】大括号的使用约定。如果是大括号内为空,则简洁地写成{}即可,不需要换行;如果是非空代码块则:

    1) 左大括号前不换行。

    2) 左大括号后换行。

    3) 右大括号前换行。

    4) 右大括号后还有 else 等代码则不换行;表示终止的右大括号后必须换行。

  2. 【强制】左小括号和字符之间不出现空格;同样,右小括号和字符之间也不出现空格;而左大括号前需要空格。详见第 5 条下方正例提示。

    反例:if (空格 a == b 空格)

  3. 【强制】if/for/while/switch/do 等保留字与括号之间都必须加空格。

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

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

  5. 【强制】采用 4 个空格缩进,禁止使用 tab 字符。

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

    正例: (涉及 1-5 点)

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    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");
    // 在右大括号后直接结束,则必须换行
    }
    }
  6. 【强制】注释的双斜线与注释内容之间有且仅有一个空格。正例:

    1
    2
    3
    // 这是示例注释,请注意在双斜线之后有一个空格

    String ygb = new String();
  7. 【强制】单行字符数限制不超过 120 个,超出需要换行,换行时遵循如下原则:

    1) 第二行相对第一行缩进 4 个空格,从第三行开始,不再继续缩进,参考示例。

    2) 运算符与下文一起换行。

    3) 方法调用的点符号与下文一起换行。

    4) 方法调用中的多个参数需要换行时,在逗号后进行。

    5) 在括号前不要换行。

    正例:

    1
    2
    3
    4
    5
    6
    7
    8
    StringBuffer sb = new StringBuffer();

    // 超过 120 个字符的情况下,换行缩进 4 个空格,点号和方法名称一起换行 sb.append("zi").append("xin")...
    .append("huang")...

    .append("huang")...

    .append("huang");
  8. 【强制】方法参数在定义和传入时,多个参数逗号后边必须加空格。

    正例:下例中实参的 args1,后边必须要有一个空格。

    method(args1, args2, args3);

  9. 【强制】IDE 的 text file encoding 设置为 UTF-8; IDE 中文件的换行符使用 Unix 格式,不要使用 Windows 格式。

(四) OOP 规约

  1. 【强制】所有的覆写方法,必须加@Override 注解。

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

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

    1) 【推荐】所有的 POJO 类属性必须使用包装数据类型。

    2) 【推荐】RPC 方法的返回值和参数必须使用包装数据类型。

    3) 【推荐】所有的局部变量使用基本数据类型。

  4. 【强制】序列化类新增属性时,请不要修改 serialVersionUID 字段,避免反序列失败;如果完全不兼容升级,避免反序列化混乱,那么请修改 serialVersionUID 值。

  5. 【强制】构造方法里面禁止加入任何业务逻辑,如果有初始化逻辑,请放在 init 方法中。

  6. 【强制】POJO 类必须写 toString 方法。如果继承了另一个 POJO 类,注意在前面加一下 super.toString。

  7. 【强制】禁止在 POJO 类中,同时存在对应属性 xxx 的 isXxx()和 getXxx()方法。说明:框架在调用属性 xxx 的提取方法时,并不能确定哪个方法一定是被优先调用到。

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

(五) 控制语句

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

  2. 【强制】在 if/else/for/while/do 语句中必须使用大括号。即使只有一行代码,避免采用单行的编码方式:if (condition) statements;

(六) 注释规约

  1. 【强制】类、类属性、类方法的注释必须使用 Javadoc 规范,使用/**内容*/格式,不得使用// xxx方式。

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

    说明:对子类的实现要求,或者调用注意事项,请一并说明。

  3. 【强制】所有的类都必须添加创建者和创建日期。

  4. 【强制】方法内部单行注释,在被注释语句上方另起一行,使用//注释。方法内部多行注释使用/* */注释,注意与代码对齐。

  5. 【强制】所有的枚举类型字段必须要有注释,说明每个数据项的用途。

JAVA注释模板

【参考】Eclipse注释模板:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
1.文件注释:
/**
* All rights Reserved, Designed By www.infotech.vip
* @Title: ${file_name}
* @Package ${package_name}
* @Description: ${todo}(用一句话描述该文件做什么)
* @author: InfoTech
* @date: ${date} ${time}
* @version V1.0
* @Copyright: ${year} XXXXX Technology Co., Ltd. All rights reserved.
*/
2.类型(Types)注释标签(类的注释):
/**
* @ClassName: ${type_name}
* @Description: ${todo}(这里用一句话描述这个类的作用)
* @author: InfoTech
* @date: ${date} ${time}
*
* ${tags}
* @Copyright: ${year} XXXXX Technology Co., Ltd. All rights reserved.
*/
3.字段(Fields)注释标签:
/**
* @Fields ${field}: ${todo}(用一句话描述这个变量表示什么)
*/
4.构造函数标签:
/**
* @Title: ${enclosing_type}
* @Description: ${todo}(这里用一句话描述这个方法的作用)
* @param: ${tags}
*/
5.方法(Methods)标签:
/**
* @Title: ${enclosing_method}
* @Description: ${todo}(这里用一句话描述这个方法的作用)
* @param: ${tags}
* @return: ${return_type}
* @throws
*/
6.覆盖方法(Overriding Methods)标签:
/**
* <p>Title: ${enclosing_method}</p>
* <p>Description: ${todo}(这里用一句话描述这个方法的作用) </p>
* ${tags}
* ${see_to_overridden}
*/
7.代理方法(Delegate Methods)标签:
/**
* ${tags}
* ${see_to_target}
*/
8.getter方法标签:
/**
* @return ${bare_field_name}
*/
9.setter方法标签:
/**
* @param ${param} the ${bare_field_name} to set
*/

参考规范