软件编码规范JAVA.docx

软件编码规范JAVA.docx

《软件编码规范JAVA.docx》由会员分享，可在线阅读，更多相关《软件编码规范JAVA.docx（42页珍藏版）》请在冰豆网上搜索。

软件编码规范JAVA

软件编码规范（JAVA）

软件技术事业部

徐海波

2014年10月23日

修正履历

版本号

修正履历

作者

审核

0.1

初稿

徐海波

2014-10-23

目录

1.前言1

1.1编写目的1

1.2适用范围1

1.3文档负责单位1

1.4术语和符号说明1

1.5参考文档1

2.概述1

3.代码组织与风格3

3.1基本原则3

3.2缩进3

3.3长度3

3.4行宽4

3.5间隔4

3.6对齐4

3.7括号5

4.注释6

4.1基本原则6

4.2JavaDoc6

4.3文件与包注释7

4.4类、接口注释8

4.5方法注释8

4.6行内注释9

4.7其他注释9

5.命名10

5.1概述10

5.1.1统一11

5.1.2达意11

5.1.3简洁11

5.2文件名、包名12

5.3类名、接口名12

5.3.1首字母大写12

5.3.2前缀12

5.3.3后缀13

5.4方法名14

5.5域（field）名15

5.5.1静态常量15

5.5.2变量和参数15

5.5.3组件/部件16

5.5.4神秘的数16

5.5.5其他17

6.应用实践17

6.1类与接口17

6.1.1基本原则17

6.1.2抽象类与接口17

6.1.3继承与组合18

6.1.4构造函数和静态工厂方法18

6.1.5toString（）,equals（）,hashCode（）...18

6.1.6SingletonClass20

6.2表达式与语句20

6.2.1基本原则20

6.2.2控制语句21

6.2.3循环语句22

6.2.4每个ifwhilefor等语句，都不要省略大括号{}23

6.3测试与Bug跟踪23

6.3.1测试驱动开发23

6.3.2Junit单元测试24

6.3.3自动测试与持续集成24

6.3.4Bug跟踪和缺陷处理24

6.4性能与安全24

6.4.1基本原则24

6.4.2String、StringBuilder、StringBugffer24

6.4.3集合25

6.4.4对象26

6.4.5同步26

6.4.6Final26

6.4.7垃圾收集和资源释放26

6.5其他27

6.5.1每次保存的时候，都让你的代码是最美的27

6.5.2使用log而不是System.out.println（）27

6.5.3善用TODO:

28

6.5.4预留代码实现需加空语句或注释28

6.5.5不要再对boolean值做truefalse判断28

6.5.6减少代码嵌套层次29

6.5.7程序职责单一31

6.5.8变量的声明，初始化和被使用尽量放到一起31

6.5.9缩小变量的作用域31

6.5.10尽量不要用参数来带回方法运算结果33

7.目录结构34

8.SVN注释与标记35

附录A词典规范36

A.1动词词典36

A.2名词词典38

1.前言

软件技术事业部负责公司内部软件、自主研发产品、合同项目等软件的开发工作，其中涉及的主要开发平台为Java，本文档是专为在JAVA开发平台上进行软件的开发设计的开发人员制定的规范。

1.1编写目的

指导软件技术事业部JAVA开发团队中的开发人员，设计人员进行代码编写和系统设计。

1.2适用范围

适用于软件技术事业部的JAVA开发设计人员。

1.3文档负责单位

软件技术事业部

1.4术语和符号说明

1.5参考文档

《Java编程指南》见RUP（RationalUnifiedProcess）中文版。

《Java技术手册》（JavainaNutshell）

《SunJava语言编码规范》（JavaCodeConventions）

《EffictiveJava》

《JavaPitfalls》

《JavaRules》

2.概述

对于代码，首要要求是它必须正确，能够按照设计预定功能去运行；第二是要求代码必须清晰易懂，使自己和其他的程序员能够很容易地理解代码所执行的功能等。

然而，在实际开发中，每个程序员所写的代码却经常自成一套，很少统一，导致理解困难，影响团队的开发效率及系统的质量等。

因此，一份完整并被严格执行的开发规范是非常必须的，特别是对软件公司的开发团队而言。

此规范参考自业界标准编程规范并结合本人多年编程经验、习惯等而制定，在本人工作过的公司中都曾参考本文档而形成内部开发规范并执行。

现在将本文档共享之，希望能对各位有所帮助，并做引玉之砖，希望各位同仁将自己的经验等增补进去。

3.代码组织与风格

3.1基本原则

代码的组织和风格的基本原则是：

便于自己的开发，易于与他人的交流。

因个人习惯和编辑器等可以设置和形成自己的风格，但必须前后一致，并符合本规范的基本要求和原则。

本章所涉及到的内容一般都可在Java集成编辑环境中进行相应设置。

3.2缩进

子功能块当在其父功能块后缩进。

当功能块过多而导致缩进过深时当将子功能块提取出来做为子函数。

代码中以TAB（4个字符）缩进，在编辑器中请将TAB设置为以空格替代，否则在不同编辑器或设置下会导致TAB长度不等而影响整个程序代码的格式。

例如：

Table1．缩进示例

publicvoidmethodName（）{

if（somecondition）{

for（…）{

//somesentences

}//endfor

}//endif

}

3.3长度

为便于阅读和理解，单个函数的有效代码长度当尽量控制在100行以内（不包括注释行），当一个功能模块过大时往往造成阅读困难，因此当使用子函数等将相应功能抽取出来，这也有利于提高代码的重用度。

单个类也不宜过大，当出现此类情况时当将相应功能的代码重构到其他类中，通过组合等方式来调用，建议单个类的长度包括注释行不超过1500行。

尽量避免使用大类和长方法。

3.4行宽

页宽应该设置为120字符。

一般不要超过这个宽度,这会导致在某些机器中无法以一屏来完整显示,但这一设置也可以灵活调整。

在任何情况下,超长的语句应该在一个逗号后或一个操作符前折行。

一条语句折行后,应该比原来的语句再缩进一个TAB或4个空格，以便于阅读。

3.5间隔

类、方法及功能块间等应以空行相隔，以增加可读性，但不得有无规则的大片空行。

操作符两端应当各空一个字符以增加可读性。

相应独立的功能模块之间可使用注释行间隔，并标明相应内容，具体参看附录的代码示例

3.6对齐

关系密切的行应对齐，对齐包括类型、修饰、名称、参数等各部分对齐。

连续赋值时当对齐操作符。

当方法参数过多时当在每个参数后（逗号后）换行并对齐。

当控制或循环中的条件比较长时当换行（操作符前）、对齐并注释各条件。

变量定义最好通过添加空格形成对齐，同一类型的变量应放在一起。

如下例所示：

Table2．对齐示例

//变量对齐-----------------------------------------------

intcount=100;

intlength=0;

StringstrUserName=null;

Integer[]porductCode=newInteger

（2）;//产品编码数组

//参数对齐----------------------------------------------

publicConnectiongetConnection（Stringurl,

StringuserName,

Stringpassword）

throwsSQLException,IOException{

}

//换行对齐----------------------------------------------

publicfinalstaticStringSQL_SELECT_PRODUCT="SELECT*"

+"FROMTProductWHEREProd_ID="

+prodID;

//条件对齐----------------------------------------------

if（Condition1//当条件一

&&Condition2//并且条件二

||Condition3）{//或者条件三

}

for（inti=0;

i

i++）{

}

3.7括号

{}中的语句应该单独作为一行，左括号"{"当紧跟其语句后，右括号"}"永远单独作为一行且与其匹配行对齐，并尽量在其后说明其匹配的功能模块。

较长的方法以及类、接口等的右括号后应使用//end...等标识其结束。

如:

类的结束符：

}//EOCClassName，

方法结束符：

}//endmethodName（），

功能块结束：

}//endif...userNameisnull?

循环快结束：

}//endfor...everyuserinuserList

不要在程序中出现不必要的括号，但有时为了增加可读性和便于理解，当用括号限定相应项。

左括号是否换行等随个人习惯而定，若换行则当与其前导语句首字符对齐。

4.注释

4.1基本原则

⏹注释宜少而精，不宜多而滥，更不能误导。

⏹命名达意，结构清晰，类和方法等责任明确，往往不需要，或者只需要很少注释，就可以让人读懂；相反，代码混乱，再多的注释都不能弥补。

所以，应当先在代码本身下功夫。

⏹不能正确表达代码意义的注释，只会损害代码的可读性。

⏹过于详细的注释，对显而易见的代码添加的注释，罗嗦的注释，还不如不写。

⏹注释要和代码同步，过多的注释会成为开发的负担。

⏹注释不是用来管理代码版本的，如果有代码不要了，直接删除，svn会有记录的，不要注释掉，否则以后没人知道那段注释掉的代码该不该删除。

4.2JavaDoc

对类、方法、变量等的注释需要符合JavaDoc规范，对每个类、方法都应详细说明其功能、条件、参数等，并使用良好的HTML标记格式化注释，以使生成的JavaDoc易阅读和理解。

JavaDoc主要提供给类的使用者来阅读的，主要介绍是什么、怎么用等信息。

凡是类的使用者需要知道，都要用JavaDoc来写。

非JavaDoc的注释，往往是个代码的维护者看的，着重告述读者为什么这样写，如何修改，注意什么问题等。

如下：

/**

*Thisisaclasscomment

*/

publicclassTestClass{

/**

*Thisisafieldcomment

*/

publicStringname;

/**

*Thisisamethodcomment

*/

publicvoidcall（）{

}

}

4.3文件与包注释

在每个文件、包的头部都应该包含该文件的功能、作用、作者、版权以及创建、修改记录等。

并在其中使用CVS标记自动跟踪版本变化及修改记录等信息。

注意是/**/注释而不是

/***/JavaDoc注释。

文件注释模板见附件《注释模板》中的文件注释部分。

版权声明部分请参见附件《版权声明》并注意更新到最新版本。

文件注释示例：

/*===========================================================

*$Id:

User.java,v1.12002/09/0714:

36:

23l_walkerExp$

*Created:

[2003-3-2320:

18:

53]byl_walker

*=========================================================

*

*ProjectName

*

*Description

*

*=========================================================

*

*CopyrightInformation.

*

*=======================================================*/

每个包当有包注释，在源码及JavaDoc相应包路径下建立package.html以描述包的功能、作用等。

4.4类、接口注释

在类、接口定义之前当对其进行注释，包括类、接口的目的、作用、功能、继承于何种父类，实现的接口、实现的算法、使用方法、示例程序等，在作者和版本域中使用CVS标记自动跟踪版本变化等，具体参看附件《注释模板》中相关部分。

类注释示例

/**

*

字符串实用类。

*

*定义字符串操作时所需要用到的方法，如转换中文、HTML标记处理等。

*

*@author$Author:

l_walker$

*@version$Revision:

1.2$$Date:

2003/05/1502:

10:

27$

*/

publicclassStringUtil{

…

}

4.5方法注释

依据标准JavaDoc规范对方法进行注释，以明确该方法功能、作用、各参数含义以及返回值等。

复杂的算法用/**/在方法内注解出。

参数注释时当注明其取值范围等

返回值当注释出失败、错误、异常时的返回情况。

异常当注释出什么情况、什么时候、什么条件下会引发什么样的异常

方法注释示例:

/**

*执行查询。

*

*该方法调用Statement的executeQuery（sql）方法并返回ResultSet结果集。

*

*@paramsql标准的SQL语句

*@returnResultSet结果集，若查询失败则返回null

*@throwsSQLException当查询数据库时可能引发此异常

*/

publicResultSetexecuteQuery（Stringsql）throwsSQLException{

//Statement和SQL语句都不能为空

if（null!

=stmt&&!

StringUtil.isEmpty（sql））{

//返回查询执行结果

returnstmt.executeQuery（sql）;

}

returnnull;

}//endexecuteQuery（）

4.6行内注释

行内注释用//写在行尾

4.7其他注释

⏹应对重要的变量加以注释，以说明其含义等。

⏹应对不易理解的分支条件表达式加注释。

不易理解的循环，应说明出口条件。

过长的方法实现，应将其语句按实现的功能分段加以概括性说明。

⏹对于异常处理当注明正常情况及异常情况或者条件，并说明当异常发生时程序当如何处理。

⏹块级别注释，单行时用//,多行时用/*..*/。

⏹较短的代码块用空行表示注释作用域

⏹较长的代码块要用/*------start:

------*/和/*--------end:

-------*/包围

如：

/*----------start:

订单处理-------*/

//取得dao

OrderDaodao=Factory.getDao（"OrderDao"）;

/*查询订单*/

Orderorder=dao.findById（456）;

//更新订单

order.setUserName（"uu"）;

order.setPassword（"pass"）;

order.setPrice（"ddd"）;

orderDao.save（order）;

/*----------end:

订单处理-------*/

⏹可以考虑使用大括号来表示注释范围

使用大括号表示注释作用范围的例子：

/*----------订单处理-------*/

{

//取得dao

OrderDaodao=Factory.getDao（"OrderDao"）;

/*查询订单*/

Orderorder=dao.findById（456）;

//更新订单

order.setUserName（"uu"）;

order.setPassword（"pass"）;

order.setPrice（"ddd"）;

orderDao.save（order）;

}

5.命名

5.1概述

命名力求做到统一、达意和简洁。

规范的命名能使程序更易阅读，从而更易于理解。

它们也可以提供一些标识功能方面的信息，有助于更好的理解代码和应用。

使用可以准确说明变量/字段/类/接口/包等的完整的英文描述符。

例如，采用类似firstName，listAllUsers或CorporateCustomer这样的名字，严禁使用汉语拼音及不相关单词命名，虽然Java支持Unicode命名，但本规范规定对包、类、接口、方法、变量、字段等不得使用汉字等进行命名。

5.1.1统一

统一是指，对于同一个概念，在程序中用同一种表示方法，比如对于供应商，既可以用supplier，也可以用provider，但是我们只能选定一个使用，至少在一个Java项目中保持统一。

统一是作为重要的，如果对同一概念有不同的表示方法，会使代码混乱难以理解。

即使不能取得好的名称，但是只要统一，阅读起来也不会太困难，因为阅读者只要理解一次。

5.1.2达意

达意是指，标识符能准确的表达出它所代表的意义，比如：

newSupplier,OrderPaymentGatewayService等；而supplier1,service2，idtts等则不是好的命名方式。

准确有两成含义，一是正确，二是丰富。

如果给一个代表供应商的变量起名是order，显然没有正确表达。

同样的，supplier1,远没有targetSupplier意义丰富。

尽量少用缩写，但如果一定要使用，当使用公共缩写和习惯缩写等，如实现（implement）可缩写成impl，经理（manager）可缩写成mgr等。

避免使用相似或者仅在大小写上有区别的名字。

5.1.3简洁

简洁是指，在统一和达意的前提下，用尽量少的标识符。

如果不能达意，宁愿不要简洁。

比如：

theOrderNameOfTheTargetSupplierWhichIsTransfered太长，transferedTargetSupplierOrderName则较好，但是transTgtSplOrdNm就不好了。

省略元音的缩写方式不要使用，我们的英语往往还没有好到看得懂奇怪的缩写。

避免使用长名字（最好不超过25个字母）。

避免使用数字，但可用2代替to，用4代替for等，如：

go2Jsp。

5.2文件名、包名

文件名当与其类严格相同，所有单词首字母大写。

包名一般以项目或模块名命名，少用缩写和长名，一律小写。

基本包：

com.sunshine，所有包、文件都从属于此包。

包名按如下规则组成：

com.[公司英文名称].[项目名文名称].[模块名].[模块功能]...

如：

Dao层：

com.sunshine.dtas.device.dao

Service层：

com.sunshine.dtas.device.service

Action层：

com.sunshine.dtas.device.action

不得将类直接定义在基本包下，所有项目中的类、接口等都当定义在各自的项目和模块包中。

5.3类名、接口名

5.3.1首字母大写

所有单词首字母大写。

使用能确切反应该类、接口含义、功能等的词，一般采用名词。

比如SupplierService,PaymentOrderAction；不要supplierService,paymentOrderAction。

5.3.2前缀

类名或接口名往往用不同的前缀表达额外的意思，如下表：

前缀名

意义

举例

Abstract

表明这个类是个基类，里面已经实现了部分方法，用于给了类继承

AbstractDesignService

Base

表明这个类是个基类，里面已经实现了部分方法，用于给了类继承

BaseController

I

这个类是一个接口

IDesignDAO

5.3.3后缀

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

后缀名

意义

举例

Service

表明这个类是个服务类，里面包含了给其他类提同业务服务的方法

PaymentOrderService

Impl

这个类是一个实现类，而不是接口

PaymentOrderServiceImpl

Inter

这个类是一个接口

LifeCycleInter

Dao

这个类封装了数据访问方法

PaymentOrderDao

Action

直接处理页面请求，管理页面逻辑了类

UpdateOrderListAction

Listener

响应某种事件的类

PaymentSuccessListener

Event

这个类代表了某种事件

PaymentSuccessEvent

Servlet

一个Servlet

PaymentCallbackServlet

Factory

生成某种对象工厂的类

PaymentOrderFactory

Adapter

用来连接某种以前不被支持的对象的类

DatabaseLogAdapter

Job

某种按时间运行的任务

PaymentOrderCancelJob

Wrapper

这是一个包装类，为了给某个类提供没有的能力

SelectableOrderListWrapper

Bean

这是一个POJO

MenuStateBean

5.4方法名

首字母小写，如addOrder（）不要AddOrder（）；动词在前，如addOrder（），不要orderAdd（）。

动词前缀往往表达特定的含义，如下表：

前缀名

意义

举例

create

创建

createOrder（）

delete

删除

deleteOrder（）

add

创建，暗示新创建的对象属于某个集合

addPaidOrder（）

remove

删除

removeOrder（）

init或则initialize

初始化，暗示会做些诸如获取资源等特殊动作

ini