JAVA编码规范

开发命名规范

JAVA编码规范

版本变更说明

版本	完稿时间	撰写人	说明
1.0	2013.5.26	石培泽	初稿

目录

1 概述... 3

1.1 编写目的... 3

1.2 原则... 3

1.3 预期读者... 4

1.4 适用范围... 4

2 命名规范... 4

2.1 包命名规则... 4

2.1.1 与业务系统相关的包命名... 4

2.1.2 与业务系统无关的、可公用的包... 5

2.2 类名、接口命名规则... 5

类名往往用不同的后缀表达额外的意思，如下表：... 6

2.3 方法命名规则... 6

2.4 变量命名规则... 8

2.5 常量命名规则... 9

3 代码书写规范... 10

3.1 返回值... 10

3.2 异常... 10

3.3 表达式... 11

3.4 体前代码... 11

3.5 注释... 12

概述

1.1 编写目的

本文描述了JAVA开发中的有关包、类、接口、方法、实例变量、变量和常量的命名规则，用于规范JAVA编程过程中的命名和代码书写规范。

原则--标识符的命名力求做到统一、达意和简洁

1.2.1、统一

统一是指，对于同一个概念，在程序中用同一种表示方法，比如对于供应商，既可以用supplier，也可以用provider，但是我们只能选定一个使用，至少在一个Java项目中保持统一。统一是作为重要的，如果对同一概念有不同的表示方法，会使代码混乱难以理解。即使不能取得好的名称，但是只要统一，阅读起来也不会太困难，因为阅读者只要理解一次。

1.2.2、达意

达意是指，标识符能准确的表达出它所代表的意义，比如： newSupplier, OrderPaymentGatewayService等；而 supplier1, service2，idtts等则不是好的命名方式。准确有两成含义，一是正确，而是丰富。如果给一个代表供应商的变量起名是 order，显然没有正确表达。同样的，supplier1, 远没有targetSupplier意义丰富。

1.2.3、简洁

简洁是指，在统一和达意的前提下，用尽量少的标识符。如果不能达意，宁愿不要简洁。比如：theOrderNameOfTheTargetSupplierWhichIsTransfered 太长， transferedTargetSupplierOrderName则较好，但是transTgtSplOrdNm就不好了。省略元音的缩写方式不要使用，我们的英语往往还没有好到看得懂奇怪的缩写。

1.2.4、骆驼法则

Java中，除了包名，静态常量等特殊情况，大部分情况下标识符使用骆驼法则，即单词之间不使用特殊符号分割，而是通过首字母大写来分割。比如: supplierName, addNewContract，而不是 supplier_name, add_new_contract。

1.2.5、英文 vs 拼音

尽量使用通俗易懂的英文单词，如果不会可以谷歌，避免拼音与英文混用。比如表示归档，用archive比较好, 用pigeonhole、guiDang则不好。

1.2 预期读者

开发组全体成员。

1.3 适用范围

适用于开发组所有基于JAVA开发的项目。

2 命名规范

2.1 包命名规则

开发组将基于JAVA开发中产生的包分为两类，一是与各业务系统相关的包，一是与业务系统无关的、可公用的包。它们的命名规则除要遵守“包名应全部是小写字母，包名中不能出现下划线，并且第一个字母不能是数字”的规则。

2.1.1 与业务系统相关的包命名

与业务系统相关的包命名格式为：

net.javaing.<projectname>.<modulename>。

其中：<projectname>为项目英文简称或缩写；<modulename>为模块英文名称或简称，如果无细分模块的话可省略模块名。

2.1.2 与业务系统无关的、可公用的包

通用包命名格式为：

net.javaing.core.<modulename>//所有项目通用

net.javaing.<projectname>.core //单个项目内各模块通用

2.2 类名、接口命名规则

类和接口的名称应是一个名词，采用大小写混和的方式，如果使用拼音则应是全拼，所有单词都应紧靠在一起，其中每个单词的首字母应大写。例如：

class User；

interface CommonConnection；

class Dept;//此处为部门英文，可使用通用的缩写，但尽量全称

每个类定义要前必须加类的说明。

附：

类名往往用不同的后缀表达额外的意思，如下表：

后缀名	意义	举例
Service	表明这个类是个服务类，里面包含了给其他类提同业务服务的方法	UserService
Impl	这个类是一个实现类，而不是接口	UserServiceImpl
Dao（Mapper）	这个类封装了数据访问方法	UserDao
Action	直接处理页面请求，管理页面逻辑了类	UpdateOrderListAction
Listener	响应某种事件的类	PaymentSuccessListener
Event	这个类代表了某种事件	PaymentSuccessEvent
Servlet	一个Servlet	PaymentCallbackServlet
Factory	生成某种对象工厂的类	UserFactory
Adapter	用来连接某种以前不被支持的对象的类	DatabaseLogAdapter
Job	某种按时间运行的任务	UserCancelJob
Wrapper	这是一个包装类，为了给某个类提供没有的能力	SelectableOrderListWrapper

2.3 方法命名规则

方法名应是一个动词或动名结构，采用大小写混和的方式，其中第一个单词的首字母用小写，其后单词的首字母大写。例如：

getDeptList()；

每个方法前必须加说明包括：方法说明、参数说明、返回值说明、异常说明。如果方法名实在是太长可以对变量名缩写，但是必须添加相应的说明。
附：

前缀名	意义	举例
save	创建	saveOrder()
delete	删除	deleteOrder()
add	创建，暗示新创建的对象属于某个集合	addPaidOrder()
remove	删除	removeOrder()
init或则initialize	初始化，暗示会做些诸如获取资源等特殊动作	initializeObjectPool
destroy	销毁，暗示会做些诸如释放资源的特殊动作	destroyObjectPool
open	打开	openConnection()
close	关闭	closeConnection()<
read	读取	readUserName()
write	写入	writeUserName()
get	获得	getName()
set	设置	setName()
prepare	准备	prepareOrderList()
copy	复制	copyCustomerList()
modity	修改	modifyActualTotalAmount()
calculate	数值计算	calculateCommission()
do	执行某个过程或流程	doOrderCancelJob()
dispatch	判断程序流程转向	dispatchUserRequest()
start	开始	startOrderProcessing()
stop	结束	stopOrderProcessing()
send	发送某个消息或事件	sendOrderPaidMessage()
receive	接受消息或时间	receiveOrderPaidMessgae()
respond	响应用户动作	responseOrderListItemClicked()
find	查找对象	findNewSupplier()
fetch	获取对象	fetch()
update	更新对象	updateCommission()
to	到达	toAddUser()

find方法在业务层尽量表达业务含义，比如 findUnsettledOrders()，查询未结算订单，而不要findOrdersByStatus()。数据访问层，find,update等方法可以表达要执行的sql，比如findByStatusAndSupplierIdOrderByName(Status.PAID, 345)

2.4 变量命名规则

变量命名一般采用大小写混和的方式，第一个单词的首字母小写，其后单词的首字母大写，变量名一般不要用下划线或美元符号开头。变量名应简短且有意义，即，能够指出其用途。除非是一次性的临时变量，应尽量避免单个字符的变量名。

（1）类的实例对象定义如下：

Person person;

（2）同一个类的多个对象可以采用一下定义方式，使用功能性（说明性）名称加类型：

Person xPerson；

Person yPerson；

（3）集合类的实例命名使用集合包含元素的英文名称的复数表示，例如：

Vector persons;

（4）如果变量名实在是太长可以对变量名缩写，但是必须在类说明或方法说明部分（视缩写的范围而定）进行说明。

（5）数组的声明要用"int[] packets"的形式，而不要用"int packets[]"。

2.5 常量命名规则

类常量和ANSI常量的命名应全部用大写，单词间用下划线隔开。例如：

final static int MIN_WIDTH = 4；

final static int MAX_WIDTH = 99；

3 代码书写规范

类的方法的代码行数不能过长，尽量控制在500行（90%），长的方法要拆分成私有函数。

3.1 返回值

在一般情况下，方法返回值不应返回null。而是尽量使用异常代替返回null。如果在特殊情况必须返回null, 必须在方法说明中加以特别说明，如使用“特别注意”等字样。例如：从一个集合类实例中提取一个对象，因为有些集合类实例是允许null作为键或值的，这个时候用异常取代返回null就不合适了。

如果方法的返回值是集合类对象，而且返回的集合对象不包含任何元素时，则应返回0长度或0大小的集合对象。不能返回null。

3.2 异常

整个应用系统使用自行设计的唯一异常类，该类包括message（表示错误信息）和ID号（整型，表示异常类型）两部分，该类在创建时是自动获得类名、方法名、行号等信息。

在系统开发和上线之后的一段时间内，异常信息要直接发送到浏览器页面，以便于开发人员迅速定位错误。

3.3 表达式

1) 所有的算术、逻辑表达式的每一项运算都需要加圆括号，避免使用java语言的运算符优先级，例如：

(2 *(x + y))/(1 - x)；

((n > 1)?(n - 1):(n = 1))

result =（result && (lastOperand > nextOperand)）；

2) 二元算术运算符（除去“/”）、二元逻辑元素符、赋值运算符，既“+、-、*、%、+=、-=、*=、/=、%=、>、<、 ==、 >=、<=、 =”等符号左右两边要加空格，例如：

if(lastOperand >= lastOperand)

3) 参数说明部分的逗号“,”和for语句循环说明部分的分号“;”之前不需要留空格，之后需要留空格。如：

Calculator.add(int a, int b);

for(int i = 0; i < 100; i ++);

3.4 体前代码

体前代码包括：

a) 方法的参数说明和异常说明；

b) 条件语句，如if语句、switch语句；

c) 循环语句，如while语句、for语句。

这些语句的参数说明、条件说明和循环控制都放在圆括号内。如果不是特别长，应尽量放在同一行内。

同时注意，参数说明、条件说明和循环控制的结束圆括号“)”与体开始花括号“{”之间留一个空格。

3.5 注释

注释是软件可读性的具体体现。程序注释量一般占程序编码量的20%，软件工程要求不少于20%。以下是四种必要的注释：

（1）类说明注释

注释一般位于 package/import 语句之前，class 描述之前。要求至少写出内容说明、创建者、创建时间和特别注意事项等内容。例如：

/**

* todo: <br>

* date:${date} ${time}<br>

* @since ${date}

* @author Javaing

*/

（2）方法说明注释

对几乎每个方法都应有适当的说明，位于方法声明之前，包括：说明，参数说明、异常说明、返回值说明和特别说明等。例如：

/**

* todo:

* @param id String唯一标识

* @param personId String 用户唯一标识

* @return obj BaseReturn 基本返回对象

* @变更记录 ${date} ${time} Javaing创建

*

*/

（3）体内代码的注释(行注释)

体(方法体、代码块体、静态代码块体等)内的代码按照功能分成多个虚拟的功能块，每个块以块注释“//”注释开始，以空行结束；例如：

//是否超级管理员

private Boolean isadmin = false;

if(null!=obj&&!obj.equals ("")){

/*组织机构ID不为空时*/

obj = '000000';

空行

}

空行

if(obj==null)

{

/*组织机构ID为空时 */

}

3.6 使用注解

@Override必须使用

@author必须使用

@deprecated必须使用

@Deprecated的作用是对不应该在使用的方法添加注解，当编程人员使用这些方法时，将会在编译时显示提示信息，它与javadoc里的@deprecated标记有相同的功能，准确的说，它还不如javadoc @deprecated，因为它不支持参数。推荐使用@deprecated

@SuppressWarnings不推荐使用，尽量从代码方面消除

@unchecked，执行了未检查的转换时的警告，不推荐使用，尽量从代码方面消除

serial，当在可序列化的类上缺少serialVersionUID 定义时的警告，推荐使用