java开发规范

java编程规范补充说明

2019-09-05 初版

 

一、命名规范

 

1. 类和接口命名：

关于前缀与后缀，前缀摘要用于方便区分java文件（包括前段文件jsp/js都应该有前缀）所属模块，比如财务以Acc开头、工资以Salary开头、人事Hr、物资Wz、流程Flow等，各开发组的可组长或组内成员协商而定。新表和实体类的创建也要按该要求添加前缀，前缀的大小写遵守《2.软件编程规范----2.1、2.2、2.3》中的规则。

后缀主要用于区分java文件承担的功能类型，控制层文件Action以Action结尾；service用Service结尾，实现类用ServiceImpl结尾；工具类用Util结尾。

补充说明：新版service接口不再以字母“I”开头，直接以各自业务前缀开头即可。

 

2. 方法命名：

方法中，存取属性的方法采用setter 和 getter方法，动作方法采用动词和动宾结构。

 

格式：

get + 非布尔属性名() 

is + 布尔属性名() 

set + 属性名() 

动词() 

动词 + 宾语() 

 

示例：

public String getType(); 

public boolean isFinished(); 

public void setVisible(boolean); 

public void show(); 

public void addKeyListener(Listener);

 

统一部分方法名开头：

Action页面跳转：to+名称()，

Service、action或其他类型：

查询数据：search+xxx，如查询用户：searchUserList()

获取数据：get+xxx，如获取用户信息：getUser()

保存数据：save+xxx，如保存凭证：saveVoucher()

新增记录：add+xxx，如新增凭证：addVoucher()

删除数据：delelte+xxx，如删除用户：deleteUser()

修改更新：update+xxx，如更新用户信息：updateUser()

检查验证：check+xxx，如检查用户编号：checkUserNo()

其他业务类操作：业务动词+xxx，如推送信息：pushMessage()

 

 

 

二、编程规范：

 

2.1、排版规范：

 

缩进：在方法体的开始、类和接口的定义、以及if、for、do、while、switch、case语句中的程序都要进行缩进，缩进的空格数为4个。if/for/while/switch/do 等保留字与括号之间都必须加空格，且都要加括号{}。

 

空格：在两个以上的关键字、变量、常量进行对等操作时，它们之间的操作符之前、之后或者前后要加空格（如：int[] numArray = {1, 2, 3};）；进行非对等操作时，如果是关系密切的立即操作符（如str.toString()的圆点，!isOk的非操作符，以及递减(--)、递增(++)等）后不应加空格。

 

换行：不允许把多个短语句写在一行中，即一行只写一条语句。相对独立的程序块之间、变量说明之后必须加空行。

一个方法尽量控制在30行以内，每行控制在80个字符，超出部分则要进行换行，换行是要注意，同组织代码的应该在同一行，例如不能把一个完整单词中间切成两行显示。

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

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

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

4） 在多个参数超长， 在逗号后换行。

5） 在括号前不要换行，见反例。

正例：

StringBuffer sb = new StringBuffer();

// 超过 80 个字符的情况下，换行缩进 4 个空格，并且方法前的点符号一起换行

sb.append("zi").append("xin")...

.append("huang")...

.append("huang")...

.append("huang");

反例：

StringBuffer sb = new StringBuffer();

// 超过 80 个字符的情况下，不要在括号前换行

sb.append("zi").append("xin")...append

("huang");// .append应该一起换行

// 参数很多的方法调用可能超过 80 个字符， 不要在逗号前换行

method(args1, args2, args3, ...

, argsX);// 逗号应在上一行

 

方法：一个方法应该只能进行一个操作，即一个方法只能完成一个功能，有多个的功能操作应该独立写成一个私有方法供其调用，如果需要继承则改成保护的，如果需要外部调用则改为公用的。每个被调用的方法应该都要有返回值，告诉调用者执行的结果。

 

2.2、编程复杂度，建议最大规模：

1、继承不能超过5层，

2、类的行数控制在1000行内，

3、一个类的方法数量原则上不能超过30个，

4、方法行数控制在30行内，

5、语句和表达式最大长度80字符，

6、方法参数5个，

7、注释覆盖率25%以上。

 

2.3、关于ajax请求：

所有Ajax请求，如果没有特殊要求，返回结果应为json格式的字符串。由miniui或其他的前端控件查询数据或请求数据的，要转换成前端控件所要求的json格式传递数据。向后台获取数据对象或数据集的，要把相应对象或集合转成json字符串后再传递。

其他非数据请求的Ajxa返回结果，比如检查是否通过或保存是否成功的结果，也应该使用json格式的字符串进行传递。建议格式可以是格式为：

{isOk:true, data:null, resultCode:1, other:"ok", resultMessage: ""}

该实体类在：com/wxtSoft/system/common/AjaxResultJsonBean.java

 

三、注释规范

 

注释最大的作用是提高程序可读性，以及记录备忘，需要注释的地方一定要加上注释。注释覆盖率25%以上，原则上注释不能超过50%，应该在适度范围内。

Java有三种注释方式：

/** 文档注释，可以通过javadoc生成API文档 */

/* 多行注释或块(block)注释 */

// 单行注释（single-line）

说明：javadoc命令有相应javadoc标签配合使用，详情可查看文档末尾的附表1

 

1. 【强制】文件注释使用块注释，放在文件最顶端，即java文件package关键字的上方，避免被javadoc收集，内容包含：版权说明、描述信息、生成日期、修改日志。

 

2. 【强制】类、类属性、类方法、域、构造函数、方法的注释必须使用 Javadoc 规范，使用文档注释的方式，不得使用//xxx 方式。 

类和接口注释内容应该包含：版本号、生成日期、作者、模块目的/功能、主要函数及其功能等。

 

 

 

3.【强制】方法的注释内容应包含：功能描述、参数说明、返回值等。详细参考《开发规范》

 

 

 

4.【强烈建议】为了增强常量，全局变量、局部变量和结构代码块的可读性，都应该做注释，应该说只要不是一眼看懂的都要有注释。

对变量的定义和分支语句（条件分支、循环语句等）应编写注释；

全局变量要有较详细的注释，建议使用文档注释，包括对其功能、取值范围、哪些函数或过程存取它以及存取时注意事项等的说明；

注释与所描述内容进行同样的缩进；

修改代码同时更新相应的注释，保证注释与代码的一致性。不再有用的注释要删除。

 

 

 

 

 

 

四、防SQL注入：

 

如何用到拼接条件的SQL语句，只要是存在SQL注入可能的条件字符串，都要做防注入处理。推荐使用apache工具包common-lang里的工具类StringEscapeUtils的escapeSql(str)方法做处理，这是当前使用最常用的防SQL注入方式。处理过程是：先将条件字符串通过StringEscapeUtils的escapeSql(str)方法处理后，再拼接到SQL语句字符串中。注意：千万不要对整个SQL用escapeSql做处理。例如下图所示：

 

 

 

 

 

 

五、审查机制：统一代码风格和编程规范是每个软件公司必要的工作。每个开发人员都应该严格遵守以上所述的开发规范。为了以上规范内持续、有效执行下来，每个小组的组长要对各自组员提交的代码做好审查工作。若发现编程不规范，则属于开发工作未完成，相关代码将视为无效，要求相关开发人员重做，直到符合编程规范为止。

  

 

附表1：

javadoc是Sun公司提供的一个技术，它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的API帮助文档。

javadoc命令是用来生成自己API文档的，使用方式：在dos中在目标文件所在目录输入javadoc +文件名.java。

标签	说明	JDK 1.1 doclet	标准doclet	标签类型
@author 作者	作者标识	√	√	包、 类、接口
@version 版本号	版本号	√	√	包、 类、接口
@param 参数名 描述	方法的入参名及描述信息，如入参有特别要求，可在此注释。	√	√	构造函数、 方法
@return 描述	对函数返回值的注释	√	√	方法
@deprecated 过期文本	标识随着程序版本的提升，当前API已经过期，仅为了保证兼容性依然存在，以此告之开发者不应再用这个API。	√	√	包、类、接口、值域、构造函数、 方法
@throws异常类名	构造函数或方法所会抛出的异常。		√	构造函数、 方法
@exception 异常类名	同@throws。	√	√	构造函数、 方法
@see 引用	查看相关内容，如类、方法、变量等。	√	√	包、类、接口、值域、构造函数、 方法
@since 描述文本	API在什么程序的什么版本后开发支持。	√	√	包、类、接口、值域、构造函数、 方法
{@link包.类#成员 标签}	链接到某个特定的成员对应的文档中。		√	包、类、接口、值域、构造函数、 方法
{@value}	当对常量进行注释时，如果想将其值包含在文档中，则通过该标签来引用常量的值。		√(JDK1.4)	静态值域

此 外还有@serial、@serialField、@serialData、{@docRoot}、{@inheritDoc}、{@literal}、 {@code} {@value arg}几个不常用的标签，由于不常使用，我们展开叙述，感兴趣的读者可以查看帮助文档。