Java代码规范

命名规范

类名采用大驼峰，一般为名词，如 ArrayList

方法名采用小驼峰，一般为动词，如 ArrayList的isEmpty()

变量采用小驼峰

常量的字母全部大写，单词之间用下划线连接

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

抽象类使用Abstract或Base开头；异常类使用Exception结尾；测试类名以测试类名开始，以Test结尾

类型与中括号紧挨来定义数组，如 int[]

枚举类名带上Enum后缀，枚举成员名全部大写，单词之间用下划线连接

复合语义下，尽量使用完整的单词组合来命名，如 KeyboardShortcutsHandler、AtomicReferenceFieldUpdater

常量

常量是在作用域内保持不变的值，一般用final关键字进行修饰，根据作用域区分，分为全局常量、类内常量、局部常量。全局常量是指类的公开静态属性，使用public static final修饰；类内常量是私有静态属性，使用private static final修饰；局部常量分为方法常量和参数常量，前者是在方法或代码块内定义的常量，后者是在定义形式参数时，增加final标识，表示此参数值不能被修改。全局常量和类内常量是最主要的常量表现形式，它们的命名方式比较特殊，采用字母全部大写、单词之间加下画线的方式。而局部常量采用小驼峰形式即可。

在常量中，拒绝使用魔法值。魔法值即“共识层面”上的常量，直接以具体的数值或者字符出现在代码中。这些不知所云的魔法值极大地影响了代码的可读性和可维护性。

举个栗子：

public void getonlinePackageCourse(Long packageId, Long userId) {

if (packageId == 3) {

logger.error("线下课程,无法在线观看");

return;

}

//其他逻辑处理

PackageCourse online = packageService.getByTeacherId(userId);

if (online.getPackageId() == 2) {

logger.error("未审核课程");

return;

}

//其他逻辑处理

}

以上示例代码中，信手拈来的2和3分别表示未审核课程和线下课程，仅仅是两个数字，似乎很容易记忆。但事实上除2和3两种状态外，还有1、4、5分别代表新建、审核未通过、审核通过。在团队规模较小时，口口相传，倒也勉强能够记住这五个数字的含义，早期还有零星的注释，驾轻就熟的情况下，连注释也省了。现实是残酷的，团队迅速扩大后，课程状态个数也在逐步增加，新来的开发在上线新功能模块时，把"审核通过"和"未审核课程"对应的数字搞反了，使得课程展示错误，导致用户大量投诉。随着应用变得越来越复杂，这些魔法值几乎成了整个后台服务代码中的梦魇。团队架构师终于下定决心进行系统重构，把这些魔法值以合适的命名方式定义成全局常量。使用Enum枚举类来定义课程类型，示例代码如下：

public enum CourseTypeEnum {

/**

* 允许官方和讲师创建和运营

*/

VIDEO_COURSE(1, "录播课程"),

/**

* 只允许官方创建和运营.初始化必须设置合理的报名人数上限

*/

LIVE_COURSE(2, "直播课程"),

/**

* 只允许官方创建和运营

*/

OFFLINE_COURSE(3, "线下课程");

private int seq;

private String desc;

CourseTypeEnum(int seq, String desc) {

this.seq = seq;

this.desc = desc;

}

public int getSeq() {

return seq;

}

public String getDesc() {

return desc;

}

}

上述示例代码把课程类型分成三种：录播课程、直播课程、线下课程。枚举类型几乎是固定不变的全局常量，使用频率高、范围广，所以枚举常量都需要添加清晰的注释，比如业务相关信息或注意事项等。再把课程状态分为新课程、未审核课程、审核通过、审核未通过、已删除五种状态。考虑到后续课程状态还会再追加，并且状态没有扩展信息，所以用不能实例化的抽象类的全局常量来表示课程状态，示例代码如下:

public abstract class BaseCourseState {

public static final int NEW_COURSE = 1;

public static final int UNAUTHED_COURSE = 2;

public static final int PASSED_COURSE = 3;

public static final int NOT_PASSED_COURSE = 4;

public static final int DELETED_COURSE = 5;

}

使用重构后的常量修改原有的魔法值：

public void getPackageCourse(Long packageId, Long userId) {

if (packageId == CourseTypeEnum.OFFLINE_COURSE.getSeq()) {

logger.error("线下课程，无法在线观看");

return;

}

VideoCourse course = packageService.getByTeacherId(userId);

if (course.getState() == BaseCourseState.UNAUTHED_COURSE) {

logger.error("未审核课程");

return;

}

}

某些公认的字面常量是不需要预定义的，如 for(int i = 0;...)这里的0是可以直接使用的。

true和false也可以直接使用，但是如果具备了特殊的含义，就必须定义有意义的名称。

变量

一般情况下变量的命名需要满足小驼峰格式，命名体现业务含义即可。存在一种特殊情况，在定义类成员变量时，特别是在POJO类中，针对布尔类型的变量，命名不要加is前缀，否则部分框架解析会引起序列化错误。例如，定义标识是否删除的成员变量为Boolean isDeleted，它的getter方法也是isDeleted()，框架在反向解析的时候， “误以为"对应的属性名称是deleted，导致获取不到属性，进而抛出异常。但是在数据库建表中，推荐表达是与否的值采用is_xxx的命名方式，针对此种情况，需要在中设置，将数据表中的is_xxx字段映射到POJO类中的属性Xxx。

展示风格

缩进、空格、空行

采用4个空格缩进

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

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

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

没有必要增加若干空格使变量的赋值等号与上一行对应位置的等号对齐

如果是大括号内为空，则简洁地写成{}即可，大括号中间无须换行和空格

左右小括号与括号内部的相邻字符之间不要出现空格

左大括号前需要加空格

换行与高度

单行字符不超过120个，超出则需换行，换行遵循如下规约：

第二行相对第一行缩进4个空格，从第三行开始，不再继续缩进

运算符与下文一起换行

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

方法调用中的多个参数需要换行时，在逗号后换行

在括号前不要换行

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

除注释之外，方法签名、左右大括号、方法内代码、空行、回车及任何不可见字符的总行数，不超过80行。为什么是80行？心理学认为人对事物的印象通常不能超过3这个魔法数，三屏是人类短期记忆的极限，而80行在一般显示器上是两屏半的代码量。另外，通过对阿里代码抽样调查显示，只有不到5%的方法才会超过80行，而这些方法通常都有明显的优化空间。

控制语句

在 if、else、for、while、do-while等语句中必须使用大括号。即使只有一行代码，也需要加上大括号

在条件表达式中不允许有赋值操作，也不允许在判断表达式中出现复杂的逻辑组合。对于复杂的逻辑运算，可以赋值给一个具有业务含义的布尔变量。

// 不易于理解

if ((file.open(fileName, "w") != null) && (...) ||!(...)){

...

}

// 易于理解

final boolean existed = (file.open(fileName, "w") != null) && (...) ||!(...);

if (existed) {

...

}

多层嵌套不能超过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.");

return;

}

避免采用反逻辑运算符。如if (x < 1)而不是if (!(x >= 1))

代码注释

注释三要素

Nothing is strange

我们提倡写注释，然后才是写精简。

Less is more

从代码可读性及维护成本方面来讲,代码中的注释一定是精华中的精华。首先，真正好的代码是自解释的，准确的变量命名加上合理的代码逻辑，无须过多的文字说明就足以让其他工程师理解代码的功能。如果代码需要大量的注释来说明解释，那么工程师应该思考是否可以优化代码表现力。

Advance with the times

任何对代码的修改，都应该同时修改注释。

注释格式

Javadoc注释

类、类属性和类方法的注释必须遵循Javadoc规范，使用文档注释(/*/)的格式。

对枚举的注释是必需的。有人觉得枚举通常带了String name属性，已经简要地说明了这个枚举属性值的意思,此时注释是多余的。其实不然，因为:

注释的内容不仅限于解释属性值的含义，还可以包括注意事项、业务逻辑。如果在原有枚举类上新增或修改一个属性值，还需要加上创建和修改时间，让使用者零成本地知道这个枚举类的所有意图

枚举类的删除或者修改都存在很大的风险。不可直接删除过时属性，需要标注为过时，同时注释说明过时的逻辑考虑和业务背景

简单注释

简单注释包括单行注释和多行注释。此类注释不允许写在代码后方，必须写在代码上方，这是为了避免注释的参差不齐，导致代码版式混乱。双画线注释往往使用在方法内部，此时的注释是提供给程序开发者、维护者和关注方法细节的调用者查看的。因此，注释的作用更应该是画龙点睛的，通常添加在非常必要的地方，例如复杂算法或需要警示的特殊业务场景等。