开发规约-编程规范

一、命名规约

1 【强制】代码中的命名均不能以下划线或美元符号开始,也不能以下划线或美元符号结束。
反例： name / __name / $Object / name / name$ / Object$

2 【强制】代码中的命名严禁使用拼音与英文混合的方式,更不允许直接使用中文的方式。
3 【强制】类名使用 UpperCamelCase 风格,必须遵从驼峰形式,但以下情形例外:(领域模型的相关命名)DO / BO / DTO / VO等。
正例:MarcoPolo / UserDO / XmlService / TcpUdpDeal / TaPromotion
反例:macroPolo / UserDo / XMLService / TCPUDPDeal / TAPromotion

4 【强制】方法名、参数名、成员变量、局部变量都统一使用 lowerCamelCase 风格,必须遵从驼峰形式。
正例: localValue / getHttpMessage() / inputUserId

5 【强制】常量命名全部大写,单词间用下划线隔开,力求语义表达完整清楚,不要嫌名字长。
6 【强制】POJO 类中布尔类型的变量,都不要加 is,否则部分框架解析会引起序列化错误。
反例:定义为基本数据类型boolean isSuccess;的属性,它的方法也是isSuccess(),RPC 框架在反向解析的时候,“以为”对应的属性名称是 success,导致属性获取不到,进而抛出异常。

7 【强制】包名统一使用小写,点分隔符之间有且仅有一个自然语义的英语单词。包名统一使用单数形式,但是类名如果有复数含义,类名可以使用复数形式。
正例: 应用工具类包名为com.alibaba.open.util、类名为MessageUtils(此规则参考 spring 的框架结构)

8 【强制】杜绝完全不规范的缩写,避免望文不知义。
反例: AbstractClass“缩写”命名成 AbsClass;condition“缩写”命名成 condi,此类随意缩写严重降低了代码的可阅读性。

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

10 【强制】各层命名规约:
A) Service/DAO层方法命名规约

获取单个对象的方法用selectOne/get做前缀。
获取多个对象的方法用select/list做前缀。
获取统计值的方法用count/selectCount做前缀。
插入的方法用insert/save做前缀。
删除的方法用delete/remove做前缀。
修改的方法用update做前缀。

B) 领域模型命名规约

数据对象:xxxDO,xxx即为数据表名。
数据传输对象:xxxDTO,xxx为业务领域相关的名称。
展示对象:xxxVO,xxx一般为网页名称。
POJO是DO/DTO/BO/VO的统称,禁止命名成xxxPOJO。

二、常量定义

11【强制】不允许出现任何魔法值(即未经定义的常量)直接出现在代码中。
反例: String key=“Id#taobao_”+tradeId;
cache.put(key, value);

12 不要使用一个常量类维护所有常量,应该按常量功能进行归类,分开维护。如:缓存相关的常量放在类:CacheConsts 下;系统配置相关的常量放在类:ConfigConsts 下。

三、格式规约

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");
				// 在右大括号后直接结束,则必须换行
		}
}

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

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

正例
 
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);

四、控制语句

// 反例
if (condition) statements;
// 正例
if (condition) {}
if (condition) {
...
}

五、注释规约

16 【强制】所有的类都必须添加创建者信息。
*17【强制】类、类属性、类方法的注释必须使用 Javadoc 规范,使用/内容/格式,不得使用 //xxx 方式。
说明:在 IDE 编辑窗口中,Javadoc 方式会提示相关注释,生成 Javadoc 可以正确输出相应注释;在 IDE 中,工程调用方法时,不进入方法即可悬浮提示方法、参数、返回值的意义,提高阅读效率。

18 【强制】不要捕获 Java 类库中定义的继承自 RuntimeException 的运行时异常类,如: IndexOutOfBoundsException / NullPointerException,这类异常由程序员预检查来规避,保证程序健壮性。

//正例:
if(obj != null) {...}
 
//反例:
try { obj.method() } catch(NullPointerException e){...}

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

20【强制】finally 块必须对资源对象、流对象进行关闭,有异常也要做 try-catch。说明:如果 JDK7,可以使用 try-with-resources 方式。

21【强制】捕获异常与抛异常,必须是完全匹配,或者捕获异常是抛异常的父类。说明:如果预期对方抛的是绣球,实际接到的是铅球,就会产生意外情况。

六、日志规约

22【强制】应用中不可直接使用日志系统(Log4j、Logback)中的 API,而应依赖使用日志框架
SLF4J 中的 API,使用门面模式的日志框架,有利于维护和各个类的日志处理方式统一。

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
private static final Logger logger = LoggerFactory.getLogger(Abc.class);

23【强制】对 trace/debug/info 级别的日志输出,必须使用条件输出形式或者使用占位符的方式。

说明:logger.debug("Processing trade with id: " + id + " symbol: " + symbol); 如果日志级别是 warn,上述日志不会打印,但是会执行字符串拼接操作,如果 symbol 是对象, 会执行 toString()方法,浪费了系统资源,执行了上述操作,最终日志却没有打印。
 
正例:(条件)
if (logger.isDebugEnabled()) {
logger.debug("Processing trade with id: " + id + " symbol: " + symbol);
}
//正例:(占位符)
logger.debug("Processing trade with id: {} symbol : {} ", id, symbol);

七、其他

24【强制】获取当前毫秒数 System.currentTimeMillis(); 而不是 new Date().getTime();
说明:如果想获取更加精确的纳秒级时间值,用 System.nanoTime()。在 JDK8 中,针对统计时间等场景,推荐使用 Instant 类。