Java开发编码规范

Java开发编码规范

文档编号： GF006 编 写 人： 陈胜 审 核 人：

项目名称： JAVA开发编码规范 编写日期： 2011/6/8 审核日期： 江苏银科金典电子应用技术有限公司

文档修改历史记录

技术中心管理制度

文档修改记录 版本号 1.0 1.1

文档审核记录 版本号

拟制/修改日期 2011-6-11 2011-6-18 拟制/修改人 陈 胜 陈 胜 描述 创建文档 进一步精简规范及整合分类 审核日期 审核人 审核意见

技术中心管理制度

目 录

前言 ................................................................................................................................................... 5 规范等级说明 .................................................................................................................................... 5 1. 格式与命名规范 ........................................................................................................................ 5 1.1 缩进 ............................................................................................................................................... 5 1.2 换行 .............................................................................................................................................. 6 1.3 命名规则 ....................................................................................................................................... 6 1.4 声明 .............................................................................................................................................. 7 2. 注释规范 ................................................................................................................................... 7 2.1 注释类型....................................................................................................................................... 7

2.1.1 JavaDoc注释 ....................................................................................................................... 7 2.1.2 失效代码注释 ....................................................................................................................... 8 2.1.3 代码细节注释 ....................................................................................................................... 8

2.2 注释的格式 ................................................................................................................................... 9 2.3 注释的内容 ................................................................................................................................... 9

2.3.1 可精简的注释内容 ............................................................................................................... 9 2.3.2 推荐的注释内容 ................................................................................................................. 10 2.3.3 特殊代码注释 ..................................................................................................................... 10

3. 编程规范 ................................................................................................................................. 10 3.1基本规范 ..................................................................................................................................... 10 3.2 异常处理..................................................................................................................................... 11

技术中心管理制度

3.3 代码度量..................................................................................................................................... 11

3.3.2 方法度量 ............................................................................................................................. 11 3.3.3 其他度量 ............................................................................................................................. 11

3.4 JDK5.0 ........................................................................................................................................ 11 4. 自动代码检查 .......................................................................................................................... 12

技术中心管理制度

前 言

编写本规范的目的是为了进一步规范JAVA软件编程风格，提高软件源程序的可读性、可靠性和可重用性，提高软件源程序的质量和可维护性，减少软件维护成本。

本规范的内容包括：代码布局、注释、命名规则、声名、表达式与语句、类与接口等。 本规范分成规则性和建议性两种：对于规则性规范，要求所有软件开发人员严格执行；对于建议性规范，各项目编程人员可以根据实际情况选择执行。

自本规范实施之日起，以后新编写的和修改的代码均应执行本规范

规范等级说明

  

级别I: 默认级别，要求所有项目中的所有成员遵守。 级别II: 建议所有项目中的所有成员遵守。 级别III: 鼓励各个项目根据实际情况执行。

1. 格式与命名规范

直接使用Eclipse的自动格式化功能 (II) 以下格式只是举例

1.1 缩进

使用Tab缩进，而不是空格键，可自由缩进2，4，8字符。

技术中心管理制度

1.2 换行

每行120字符。

if,for,while语句只有单句时，如果该句可能引起阅读混淆，需要用\" {\"和\括起来，否则可以省略。

//错误，需要使用花括号{}括起来 if (condition)

if(condition) doSomething(); else

doSomething();

1.3 命名规则

 

尽量使用英文简写命名

遇到缩写如XML时，仅首字母大写，即loadXmlDocument()而不是loadXMLDocument()

 

Package名必须全部小写，尽量使用单个单词

Interface名可以是一个名词或形容词(加上'able','ible', or 'er'后缀)，如Runnable，Accessible。

为了基于接口编程，不采用首字母为I或加上IF后缀的命名方式，如IBookDao,BookDaoIF。

 页面部件名建议命名为：btnOK、lblName或okBtn、nameLbl。(II) 其中btn、lbl缩写代表按钮(Button)、标签(Label)。

技术中心管理制度

 局部变量及输入参数不要与类成员变量同名(get/set方法与构造函数除外)

1.4 声明

 修饰符应该按照如下顺序排列：public, protected, private, abstract, static, final, transient, volatile, synchronized, native, strictfp。

 类与接口的声明顺序(可用Eclipse的source->sort members功能自动排列):

1. 静态成员变量 / Static Fields 2. 静态初始化块 / Static Initializers 3. 成员变量 / Fields 4. 初始化块 / Initializers 5. 构造器 / Constructors

6. 静态成员方法 / Static Methods 7. 成员方法 / Methods

8. 重载自Object的方法如toString(), hashCode() 和main方法 9. 类型(内部类) / Types(Inner Classes)

同等的类型，按public, protected, private的顺序排列。

2. 注释规范

2.1 注释类型

2.1.1 JavaDoc注释

/*** .... **/

技术中心管理制度

2.1.2 失效代码注释

由/*...*/界定，标准的C-Style的注释。专用于注释已失效的代码。

/*

* Comment out the code * String s = \"hello\"; * System.out.println(s); */

2.1.3 代码细节注释

由//界定，专用于注释代码细节，即使有多行注释也仍然使用//，以便与用/**/注释的失效代码分开

除了私有变量外，不推荐使用行末注释。

class MyClass {

private int myField; // An end-line comment.

public void myMethod {

//a very very long //comment. if (condition1) {

//condition1 comment ... } else {

//elses condition comment

技术中心管理制度

... } } }

2.2 注释的格式

 注释中的第一个句子要以（英文）句号、问号或者感叹号结束，以便于Javadoc生成有用的API说明。

 

对于重要的或公用的类和方法必须添加功能介绍及详细参数、返回值说明。 为了在JavaDoc和IDE中能快速链接跳转到相关联的类与方法，尽量多的使用@see xxx.MyClass，@see xx.MyClass#find(String)。

 Class必须以@author 作者名声明作者，不需要声明@version与@date，由版本管理系统保留此信息。(II)

  

如果注释中有超过一个段落，用

分隔。(II) 示例代码以

标识(java keyword, class/method/field/argument名，Constants) 以包裹。(II)

 标识在第一次出现时以{@linkxxx.Myclass}注解以便JavaDoc与IDE中可以链接。(II)

2.3 注释的内容

2.3.1 可精简的注释内容

不要自动生成一堆空的标签，如果该注释信息是无效，连同标签删掉它，如空的@param name，空的@return。

技术中心管理制度

2.3.2 推荐的注释内容

  

对于调用复杂的API尽量提供代码示例。(II) 对于已知的Bug需要声明。(II)

在本函数中抛出的unchecked exception尽量用@throws说明。(II)

2.3.3 特殊代码注释

 

代码质量不好但能正常运行，或者还没有实现的代码用//TODO: 或 //XXX:声明 存在错误隐患的代码用//FIXME:声明

3. 编程规范

3.1基本规范

1. 当面对不可知的调用者时，方法需要对输入参数进行校验，如不符合抛出

IllegalArgumentException。

2. 隐藏工具类的构造器，确保只有static方法和变量的类不能被构造实例。 3. 变量，参数和返回值定义尽量基于接口而不是具体实现类，如Map map = new

HashMap();

4. 代码中不能使用System.out.println()，e.printStackTrace()，必须使用logger打

印信息。

技术中心管理制度

3.2 异常处理

1. 重新抛出的异常必须保留原来的异常，即throw new NewException(\"message\

e); 而不能写成throw new NewException(\"message\")。 2. 在所有异常被捕获且没有重新抛出的地方必须写日志。

3. 如果属于正常异常的空异常处理块必须注释说明原因，否则不允许空的catch块。 4. 框架尽量捕获低级异常，并封装成高级异常重新抛出，隐藏低级异常的细节。(III)

3.3 代码度量

3.3.1方法度量

 

方法（构造器）参数在5个以内 ( II ) 方法长度150行以内 ( II )

3.3.2其他度量

   

布尔表达式中的布尔运算符(&&,||)的个数不超过3个(III) if语句的嵌套层数3层以内(II) 文件长度2000行以内(II) 匿名内部类20行以内 ( II )

太长的匿名内部类影响代码可读性，建议重构为命名的（普通）内部类。

3.4 JDK5.0

1. 重载方法必须使用@Override，可避免父类方法改变时导致重载函数失效。

技术中心管理制度

2. 不需要关心的warning信息用@SuppressWarnings(\"unused\"),

@SuppressWarnings(\"unchecked\"), @SuppressWarnings(\"serial\") 注释。

4. 自动代码检查

使用Eclipse的代码校验功能已经排除了很多问题。

可以配合使用Check style 校验涵盖了Java编码大部分的问题。

1. Eclipse：在Windows->Preferences->Java-Compiler->Errors/Warnings中，

按本文档将一些原来Ignore的规则打开。

2. CheckStyle：安装Eclipse插件，在Windows->Preferences->CheckStyle导入

附件javacode_check.xml中预先定义的规则。

3、建议将CheckStyle与Subversion进行集成，配置一些很基本的checkstyle规则，如命名规则 ，如果违反规则Subversion就不允许提交代码(II)。