java开发规范

java编程规范补充说明

2019-09-05 初版

 

一、命名规范

 

1. 类和接口命名:

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

后缀主要用于区分java文件承担的功能类型,控制层文件ActionAction结尾;serviceService结尾,实现类用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+名称()

Serviceaction或其他类型:

查询数据: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、排版规范:

 

缩进:在方法体的开始、类和接口的定义、以及iffordowhileswitchcase语句中的程序都要进行缩进,缩进的空格数为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

java开发规范_第1张图片

 

三、注释规范

 

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

Java有三种注释方式:

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

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

// 单行注释single-line

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

 

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

 

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

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

 java开发规范_第2张图片

 

 

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

 java开发规范_第3张图片

 

 

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

对变量的定义和分支语句(条件分支、循环语句等)应编写注释;

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

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

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

 

 

 

 

 

 

四、SQL注入:

 

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

 java开发规范_第4张图片

 

 

 

 

 

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

  

 

附表1

javadocSun公司提供的一个技术,它从程序源代码中抽取类、方法、成员等注释形成一个和源代码配套的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}几个不常用的标签,由于不常使用,我们展开叙述,感兴趣的读者可以查看帮助文档。

 




你可能感兴趣的:(java开发规范)