目的

  • 使运营研发团队以标准的，规范的方式设计和进行Java编码。
  • 通过建立编码规范，以使每个开发人员养成良好的编码风格和习惯；并以此形成运营研发团队的Java编码约定，提高程序的可靠性，可读性，可修改性，可维护性和一致性等，增进团队间的交流，并保证软件产品的质量。

术语和定义

  • 规则：编程时强制必须遵守的原则。
  • 建议：编程时必须加以考虑的原则。
  • 格式：对此规范格式的说明。
  • 说明：对此规范或建议进行必要的解释。
  • 示例：对此规范或建议从正、反两个方面给出例子。

分步指南 将分为以下几个方面:

  • 排版规范
  • 注释规范
  • 命名规范
  • 编码规范
  • 性能与安全建议
  • 关键技术框架版本规定
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
排版规范
1，规则
*程序块要采用缩进风格编写，缩进的空格数为4个。
*分界符（如大括号„{‟和„}‟）应各独占一行并且位于同一列，同时与引用它们的语句左对齐。在函数体的开始、类和接口的定义、以及if、for、do、while、switch、case语句中的程序都要采用如上的缩进方式。
*较长的语句、表达式或参数（>80字符）要分成多行书写，长表达式要在低优先级操作符处划分新行，操作符放在新行之首，划分出的新行要进行适当的缩进，使排版整齐，语句可读。
*不允许把多个短语句写在一行中，即一行只写一条语句。
*if, for, do, while, case, switch, default 等语句自占一行，且if, for, do, while等语句的执行语句无论多少都要加括号{}。
*相对独立的程序语句之间、变量说明之后应当加空行。类，方法及功能块间等应以空行相隔，以增加可读性，但不得有无规则的大片空行。操作符两端应当各空一个字符以增加可读性。
*对齐只使用空格键，不使用TAB键（\t）。
*在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或者前后要加空格；进行非对等操作时，如果是关系密切的立即操作符（如.），后不应加空格。
2，建议
*类属性和类方法不要交叉放置，不同存取范围的属性或者方法也尽量不要交叉放置。
格式：
class Clasz {
public static Field fieldName;
protected static Field fieldName;
private static Field fieldName;
public Field fieldName;
protected Field fieldName;
private Field fieldName;
public static ReturnValue method(Parameter paremeter) {} 
}
*单个函数的有效代码长度当尽量在40行以内，当功能模块过大时往往采用使用子函数将相应的功能抽取出来，这也有利于提高代码的重用度。
*单个类不宜过大，当出现此类过大时当将相应功能的代码重构到其他类中，通过组合等方式来调用，建议单个类的长度包括注释行不超过500行。尽量避免使用大类和长方法。
1
2
3
4
5
6
7
8
9
10
11
注释规范
1：注释应该增加代码的清晰度。代码注释的目的时要使代码更易于被其他开发人员等理解。
2：保持注释的简洁。
3：注释信息应该包括代码的功能。
4：除变量定义等较短语句的注释使用行尾注释外，其他注释当避免使用行尾注释。
5：JavaDoc 规范
对类，方法，变量等注释需要符合javadoc规范，对每个类，方法都应详细说明其功能条件，参数等。类注释中应当包含版本和作者信息。
1）类，接口注释 在类，接口定义之前当对其进行注释，包括类，接口的目的，作用，功能，继承于何种父类，实现的接口，实现的算法，使用方法，示例程序等。
2）方法注释 以明确该方法功能，作者，各参数含义以及返回值等。
3）其他注释 应对重要的变量及不易理解的分支条件表达式加以注释，以说明其含义等。
(PS: 鉴于当前项目紧急，暂不对注释做过多地要求，但应做到代码不用无意义的语句单词，从而做到代码即注释)
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
命名规范
1，规则
1. 包名采用域后缀倒置的加上自定义的包名，采用小写字母。在部门内部应该规划好包名的范围，防止产生冲突。部门内部产品使用部门的名称加上模块名称。产品线的产品使用产品的名称加上模块的名称。
格式：com.enmonster.[部门群组名].[项目名] 
示例：在gitlab中，运营研发团队的群组名称是 optimon，其中有个CRM项目被叫做portray, 那么该项目下的包名应该为 com.enmonster.optimon.portray
2. 类名和接口; 使用类意义完整的英文描述的驼峰命名法，每个英文单词的首字母使用大写、其余字母使用小写的大小写混合法。
示例：OrderInformation, CustomerList, LogManager, LogConfig, SmpTransaction 
3. 方法名；使用类意义完整的英文描述的驼峰命名法：第一个单词的字母使用小写、剩余单词首字母大写其余字母小写的大小写混合法。
示例：
private void calculateRate(); 
public void addNewOrder(); 
4. 方法中，存取属性的方法采用setter 和getter方法，动作方法采用动词和动宾结构。
格式：
get + 非布尔属性名() 
is + 布尔属性名() 
set + 属性名()
动词() 
动词 + 宾语() 
示例：public String getType(); 
public boolean isFinished(); 
public void setVisible(boolean); 
public void show(); 
public void addKeyListener(Listener); 
5. 属性名使用意义完整的英文描述的驼峰式命名法：第一个单词的字母使用小写、剩余单词首字母大写其余字母小写的大小写混合法。属性名不能与方法名相同。
示例：private customerName; 
private orderNumber; 
private smpSession; 
6. 常量名使用全大写的英文描述，英文单词之间用下划线分隔开，并且使用final static 修饰。
示例：public final static int MAX_VALUE = 1000; 
public final static String DEFAULT_START_DATE = "2001-12-08"; 
7. 属性名可以和公有方法参数相同，不能和局部变量相同，引用非静态成员变量时使用 this引用，引用静态成员变量时使用类名引用。
2，建议
1. 常用组件类的命名以组件名加上组件类型名结尾。
示例：Application 类型的，命名以Application 结尾——MainApplication 
Frame 类型的，命名以Frame 结尾——TopoFrame 
Panel 类型的，建议命名以Panel 结尾——CreateCircuitPanel 
Bean 类型的，建议命名以Bean 结尾--------DataAccessBean
2. 如果函数名超过15 个字母，可采用以去掉元音字母的方法或者以行业内约定俗成的缩写方式缩写函数名。
示例：getCustomerInformation()  可用 getCustomerInfo() 
3. 准确地确定成员函数的存取控制符号，不是必须使用public 属性的，请使用 protected，不是必须使用protected, 请使用 private。
4. 含有集合意义的属性命名，尽量包含其复数的意义。
示例：customers,  orderItems
1
2
3
4
5
6
7
8
9
10
11
12
13
14
编码规范
1，规则
1. *明确方法功能，精确（而不是近似）地实现方法设计。一个函数仅完成一件功能，即使简单功能也应该编写方法实现。复杂度不宜太深，最多4层
说明：虽然为仅用一两行就可完成的功能去编方法好象没有必要，但用方法可使功能明确化，增加程序可读性，亦可方便维护、测试。
2. 应明确规定对接口方法参数的合法性检查应由方法的调用者负责还是由接口方法本身负责，缺省是由方法调用者负责。
说明：对于模块间接口方法的参数的合法性检查这一问题，往往有两个极端现象，即：要么是调用者和被调用者对参数均不作合法性检查，结果就遗漏了合法性检查这一必要的处理过程，造成问题隐患；要么就是调用者和被调用者均对参数进行合法性检查，这种情况虽不会造成问题，但产生了冗余代码，降低了效率。
3. 明确类的功能，精确（而不是近似）地实现类的设计。一个类仅实现一组相近的功能。
说明：划分类的时候，应该尽量把逻辑处理、数据和显示分离，实现类功能的单一性。
示例：数据类不能包含数据处理的逻辑。通信类不能包含显示处理的逻辑。
4. 所有的数据类必须重载toString() 方法，返回该类有意义的内容。
说明：父类如果实现了比较合理的toString() ，子类可以继承不必再重写。
5. 数据库操作、IO操作等需要使用结束close()的对象必须在try -catch-finally 的finally中close()。
6. 异常捕获后，如果不对该异常进行处理，则应该纪录日志或者ex.printStackTrace() 。
说明：若有特殊原因必须用注释加以说明。
1
2
3
4
5
6
7
8
性能与安全建议
建议
1：不要使用String string = new String("abc")；这将产生2个对象，应当使用String string = ”abc”；
2：处理可变字符串时候尽量使用StringBuilder类；
3：尽量避免使用Vector 和HashTable等旧的集合实现。由于时实现时同步的，故大量操作带来不必要的性能损失。应使用ArrayList和HashMap来代替。如果一定要使用同步集合类，当使用如下方式：Map map=Collections.synchronizedMap（new HashMap（））；
4：避免在循环中频繁的构建和释放对象。
5：如无必要，不要序列化对象；
6：垃圾收集和资源释放，可能有异常的操作时必须在try的finally块中释放资源，如数据库连接，I/O操作等
1
2
3
4
5
6
7
8
9
10
11
12
13
14
关键技术框架版本规定
1，规则
以下几个技术框架选型版本，在未经沟通，禁止随意更新，升级，降级。
* OS, Centos 7.3 (1611) (开发环境不受此条约束)
* Java/JDK/JRE 版本 1.8 1.8_141
* MySQL 5.7.18
* Spring Framework Boot: 1.5.4.RELEASE
* Spring Framework: 4.3.9.RELEASE
* Hibernates 5.0.12.Final . (auto import by Spring boot starter data jpa 1.5.4.RELEASE )
* MyBatis 3.4.4
* Gradle version: 4.0.1 (与maven二选一)
* Maven version: 3.5.0 (与gradle二选一)
2， 建议
其他框架的版本的定义在 Maven/Gradle中的依赖描述中定义 ，未经商议，不要擅自升级，降级。