java开发规范

╰半橙微兮° 2022-06-07 23:24 232阅读 0赞

**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");

反例：

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

![20170908133059531][]

三、**注释规范**

** **

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

Java有三种注释方式：

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

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

// 单行注释（single-line）

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

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

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

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

![20170908133155993][]

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

![20170908133228215][]

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

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

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

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

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

四、**防SQL注入：**

** **

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

![20170908133302557][]

** **

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

附表1：

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

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

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

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

[20170908133059531]: /images/20220608/fb0c1bf39405496fae5070c30ccd4f22.png
[20170908133155993]: /images/20220608/a59d8c94bf734bc89df32a620e271405.png
[20170908133228215]: /images/20220608/3300892f99674a78a3100725446bece5.png
[20170908133302557]: /images/20220608/81b81f58e72d4ab68b22278ed84fcb10.png