Java编码指南.docx
- 文档编号:4444156
- 上传时间:2022-12-01
- 格式:DOCX
- 页数:19
- 大小:32.03KB
Java编码指南.docx
《Java编码指南.docx》由会员分享,可在线阅读,更多相关《Java编码指南.docx(19页珍藏版)》请在冰豆网上搜索。
Java编码指南
RD
中国民航信息网络股份有限公司制度
JAVA编码规范
文件编号:
版本号:
VER1.0.0
编制部门:
中国民航信息网络股份有限公司研发中心产品开发部
编制人:
陈福荣
编制日期:
2009.04.13
审批人:
XXX
审批日期:
2009.**.**
变更记录
序号
修改
原因
修改
目的
修改内容
修改人/日期
审批人/日期
修改后的版本号
实施日期
目录
1目的4
2名词解释与定义4
3代码组织与风格4
3.1基本原则4
3.2代码样式4
3.3缩进5
3.4长度5
3.5行宽5
3.6{}5
3.7()5
3.8间隔6
3.9对齐6
3.10风格6
4注释6
4.1基本原则6
4.2JavaDoc6
4.3文件与包的注释7
4.4类、接口注释7
4.5方法注释8
4.6其它注释8
4.7注释参考表9
5命名10
5.1基本原则10
5.2文件和包11
5.3类和接口11
5.4字段11
5.5方法12
5.6异常12
5.7命名约定列表12
6声明13
6.1包13
6.2类,接口14
6.3方法14
6.4字段14
7其它注意事项15
7.1表达式和语句15
7.2异常15
7.3日志15
7.4移植性16
7.5性能考虑16
1目的
本文的目的是使研发中心能以标准的,规范的方式进行JAVA语言编码及测试,使开发人员养成良好的编码风格和习惯,它们以安全可靠的软件工程原则为基础,使代码易于理解、维护和扩展,具体体现为以下几项内容:
Ø规范JAVA语言编码注释风格以及基本的约定
Ø规范单元测试方式方法
Ø规范集成测试方式方法
本规范是所有以Java为主要开发语言的项目的通用规范,由于基于JAVA的系统规范,框架非常丰富,在具体项目中,可基于本规范再制定实施细则。
2名词解释与定义
3代码组织与风格
3.1基本原则
代码的组织和风格的基本原则是:
便于自己的开发,易于与他人的交流。
因个人习惯和编辑器等可以设置和形成自己的风格,但必须前后一致,并符合本规范的基本要求和原则。
本规范所涉及到的内容一般都可在Java集成编辑环境中进行相应设置,以达到项目整体统一。
3.2代码样式
代码可使用unix或windows(比如:
回车变成回车+换行)的格式,但在一个项目中,应该统一使用一种风格。
3.3缩进
缩进应该是每行2个空格的倍数(一般为4个空格)。
当功能太多导致缩进太深时(如已接近或超出下面所述的行宽时),应剥离出子函数。
3.4长度
单个函数长度建议不应大于150行(不包括注释行),超过时应当考虑使用子函数。
单个类建议不超过2000行(不包括注释行),当出现该情况时,可使用继承,组合等方式将部分功能转移到其它类中。
尽量避免大类和长方法。
3.5行宽
页宽应该设置为80字符。
源代码一般不应超过这个宽度。
在任何情况下,超长的语句应该在一个逗号或者一个操作符后折行。
一条语句折行后,应该比原来的语句再使用缩进格式。
当声明函数参数需要折行时,应将参数对齐。
3.6{}
“{“可以紧跟在代码之后,也可作为单独一行(此时,需与前导语句的首字母对齐),但一个产品的风格应该统一,可以在开发环境的格式化模板中进行定义。
“{“紧跟在代码之后时,之间应留一空格。
“}”中的语句应该单独作为一行。
3.7()
左括号和后一个字符之间不应该出现空格,同样,右括号和前一个字符之间也不应该出现空格,下面的例子说明括号和空格的错误及正确使用:
CallProc( AParameter ); // 错误
CallProc(AParameter); // 正确
不要在语句中使用无意义的括号. 括号只应该为达到某种目的而出现在源代码中。
下面的例子说明错误和正确的用法:
if ((I) = 42) { // 错误 - 括号毫无意义
if (I == 42) or (J == 42) then // 正确 - 的确需要括号
3.8间隔
Ø类、方法及功能块间等应以空行相隔,以增加可读性,但不得有无规则的大片空行。
Ø在=,+,-,*,/等操作符的两侧应使用一个空格以增强代码的可读性。
如:
a=b+c
Ø相应独立的功能模块之间可使用注释行间隔,并标明相应内容。
3.9对齐
Ø关系密切的行应对齐,对齐包括类型、修饰、名称、参数等各部分对齐。
Ø连续赋值时应当对齐操作符。
Ø当方法参数过多时当在每个参数后(逗号后)换行并对齐。
Ø当控制或循环中的条件比较长时当换行(操作符前)、对齐并注释各条件。
Ø变量定义最好通过添加空格形成对齐,同一类型的变量应放在一起。
3.10风格
Ø一个项目的所有代码应使用一致的风格。
Ø对每个文件、类、接口、方法等都应有较详细的注释。
Ø不允许把多个语句放在一行,即一行只写一条语句。
Ø较长的方法以及类、接口等的右括号后应使用//end...标识其结束。
Ø修改他人程序时,应尽可能的保持原有风格。
4注释
4.1基本原则
注释应该增加代码的清晰度。
代码注释的目的是要使代码更易于被同时参与程序设计的开发人员以及其他后继开发人员理解。
保持注释的简洁。
注释信息不仅要包括代码的功能,还应给出原因。
尽量不使用行末注释。
4.2JavaDoc
对类、方法、变量等的注释需要符合JavaDoc规范,对每个类、方法都应详细说明其功能、条件、参数等,并使用良好的HTML标记格式化注释,以使生成的JavaDoc易阅读和理解。
4.3文件与包的注释
在每个源文件的头部都应该对该文件的功能、作用、作者、版权以及修改记录等进行注解。
可以参考如下模板:
/**============================================================
*版权:
Travelsky版权所有(c)2007-2009
*文件:
com.traveksky.util.Configuration
*所含类:
Configuration
*修改记录:
*日期作者内容
*=============================================================
*2008-12-25张**创建文件,实现基本功能
*2009-01-02李**添加getProperties()
*2009-01-19张**getValue时汉字编码问题
*============================================================*/
每个包当有包注释,在源码及JavaDoc相应包路径下建立package.html以描述包的功能、作用等
4.4类、接口注释
在类、接口定义之前当对其进行注释,包括类、接口的目的、作用、功能、继承于何种父类,实现的接口以及重大的修改记录等等,基本依据标准的JavaDoc规范。
/**
*
字符串实用类。
*
*
定义字符串操作时所需要用到的方法,如转换中文、HTML标记处理
*
*
Copyright:
版权所有(c)2007-2009
*
Company:
Travelsky
*
*@author李**
*@version2.0.1
*/
publicclassStringUtil{
…
}
4.5方法注释
依据标准JavaDoc规范对方法进行注释,以明确该方法功能、作用、各参数含义以及返回值等。
复杂的算法用/**/在方法内注解出。
/**
*执行查询。
*
*该方法调用Statement的executeQuery(sql)方法并返回ResultSet结果集。
*
*@paramsqlSQL语句
*@returnResultSet结果集
*@throwsSQLExceptionSQL异常
*/
publicResultSetexecuteQuery(Stringsql)throwsSQLException{
if(null!
=stmt){
returnstmt.executeQuery(sql);
}
returnnull;
}//endexecuteQuery()
4.6其它注释
应对重要的变量加以注释,以说明其含义。
应对不易理解的分支条件表达式加注释。
不易理解的循环,应说明出口条件。
过长的方法实现,应将其语句按实现的功能分段加以概括性说明。
对于异常处理注明正常情况及异常情况或者条件,并说明当异常发生时程序当如何处理。
单行语句注解应当比其注解的语句缩进两个字符。
4.7注释参考表
项目
注释部分
参数
参数类型
参数用来做什么
任何约束或前提条件
示例
字段/属性
字段描述
注释所有使用的不变量
示例
并行事件
可见性决策
类
类的目的
已知的问题
类的开发/维护历史、版本
注释出采用的不变量
并行策略
编译单元
每一个类/类内定义的接口,含简单的说明
文件名和/或标识信息
修改/维护记录
版权信息
获取成员函数
若可能,说明为什么使用滞后初始化
接口
目的
它应如何被使用以及如何不被使用
局部变量
用处/目的
成员函数注释
成员函数做什么以及它为什么做这个
哪些参数必须传递给一个成员函数
成员函数返回什么
已知的问题
任何由某个成员函数抛出的异常
可见性决策
成员函数是如何改变对象的
包含任何修改代码的历史
如何在适当情况下调用成员函数的例子
适用的前提条件和后置条件
成员函数内部注释
控制结构
代码做了些什么以及为什么这样做
局部变量
难或复杂的代码或代码
处理顺序
包
包的基本原理
包中的类
功能和用途
包的开发/修改/维护/版本信息
版权信息
标准的JDK中有一个名为javadoc的程序。
它可以处理Java的源代码文件,并且为Java程序产生HTML文件形式的外部注释文档。
Javadoc支持一定数目的标记,标识注释文档中各段起始位置的保留字。
详情请参考JDKjavadoc文档。
标记
用于
目的
@authorname
类、
接口
说明特定某一段程序代码的作者。
每一个作者各有一个标记。
@deprecated
类、
成员函数
说明该类的应用程序编程接口(API)已被废弃,因此应不再使用。
@exceptionnamedescription
成员函数
说明由成员函数发出的异常。
一个异常采用一个标记,并要给出异常的完整类名。
@paramnamedescription
成员函数
用来说明传递给一个成员函数的参数,其中包括参数的类型/类和用法。
每个参数各有一个标记。
@returndescription
成员函数
若成员函数有返回值,对该返回值进行说明。
应说明返回值的类型/类和可能的用途。
@since
类、成员函数
说明自从有JDK1.1以来,该项已存在了多长时间。
@seeClassName
类、接口、成员函数、字段
在文档中生成指向特定类的超文本链接。
可以并且应该采用完全合法的类名。
@seeClassName#memberfunctionName
类、接口、成员函数、字段
在文档中生成指向特定成员函数的超文本链接。
可以并且应该采用完全合法的类名。
@versiontext
类、接口
说明特定一段代码的版本信息。
5命名
5.1基本原则
任何时候,都不使用中文来命名JAVA中的相关元素(包,文件,类,方法,变量等),
而使用可以准确说明变量/字段/类的完整的英文描述符。
例如,采用类似firstName,grandTotal或CorporateCustomer这样的名字。
采用大小写混合,提高名字的可读性。
一般应该采用小写字母,但是类和接口的名字的首字母,以及任何中间单词的首字母应该大写。
包名全部使用小写字母
尽量少用缩写,但如果一定要使用,各项目需定义相应的数据字典,可以使用一些约定俗成的缩写,实现(implement)可缩写成impl,经理(manager)可缩写成mgr等。
避免使用长名字(最好不超过25个字母)。
避免使用相似或者仅在大小写上有区别的名字。
避免使用数字,但可用2代替to,用4代替for等,如:
log4j。
某些循环临时变量,也可用单个字母命名,如i,j。
5.2文件和包
文件名当与其类严格相同,所有单词首字母大写。
包名一般以项目或模块名命名,少用缩写和长名,一律小写。
基本包:
com.travelsky,所有包、文件都从属于此包。
包名按如下规则组成:
[基本包].[项目名].[模块名].[子模块名]...如:
com.travelsky.newapp.fdc.changeplane
不得将类直接定义在基本包下,所有项目中的类、接口等都当定义在各自的项目和模块包中。
5.3类和接口
所有单词首字母大写。
应当能间接而确切地反应该类、接口的含义。
一般采用名词。
5.4字段
常量:
一般中static final修饰,采用完整的英文大写单词,在词与词之间用下划线连接,程序中尽量不出现未经任何定义便到处使用的数字,应将其定义为常量后再使用。
变量:
对不易清楚识别出该变量类型的变量应使用类型缩写作其前缀,如字符串使用strXXX,boolean使用isXXX,hasXXX等等。
除第一各个单词外其余单词首字母大写。
命名时应使用复数来表示它们代表多值。
如:
orderItems。
组件/部件:
对UI相关的代码中,常会有按钮,文本框等成员变量,应以组件的类别或类别简称为前缀命名,如btnQuery,txtFltNo,txtDate。
集合:
一个集合,例如数组和矢量,应采用复数命名来表示队列中存放的对象类型。
命名应采用完整的英文描述符,名字中所有非开头的单词的第一个字母应大写,适当使用集合缩写前缀。
如:
orderItems,aryUsers。
5.5方法
方法的命名应采用完整的英文描述符,大小写混合使用:
首字母小写,所有中间单词的第一个字母大写。
方法名称的第一个单词常常采用一个有强烈动作色彩的动词。
取值类使用get前缀,设值类使用set前缀,判断类使用is(has)前缀。
例:
getName(),setSalary(),isLogin()
方法参数建议顺序:
(被操作者,操作内容,操作标志,其他…),例:
publicvoidreplace(StringsourceStr,StringoldStr,StringnewStr)
对于有不同参数类型或个数的重载方法,应以递增的形式书写,即参数少的写在前面,依次递增。
5.6异常
异常类名由表示该异常类型的单词和Exception组成,如ActionException。
异常实例一般使用e、ex等,在多个异常时使用该异常名或简写加E,Ex等组成,如:
SQLExActionEx
5.7命名约定列表
操作项
命名约定
示例
参数
使用传递值/对象的完整的英文描述符。
UserID
字段/属性
字段采用完整的英文描述,第一个字母小写,任何中间单词的首字母大写。
firstName
布尔型的获取成员函数
所有的布尔型获取函数必须用单词is(has)做前缀。
isString(),hasMoney()
类
采用完整的英文描述符,所有单词的第一个字母大写。
Customer
编译单元文件
使用类或接口的名字,或者如果文件中除了主类之外还有多个类时,加上前缀java来说明它是一个源码文件。
Customer.java
析构函数
Java没有析构函数,但一个对象在垃圾收集时,调用成员函数finalize(),尽可能不使用该方法。
finalize()
异常
通常采用字母e表示异常。
e或ex
静态常量字段(常量)
全部采用大写字母,单词之间用下划线分隔。
采用静态常量获取成员函数。
DEFAULT_NAME
获取成员函数
被访问字段名的前面加上前缀get。
getUserName()
接口
采用完整的英文描述符说明接口封装,所有单词的第一个字母大写。
使用I前缀,其后使用able,.ible或者er等后缀,但这不是必需的。
IRunnable
Runnable
IPrompter
局部变量
采用完整的英文描述符,第一个字母小写,但不要隐藏已有字段。
例如,如果有一个字段叫firstName,不要让一个局部变量叫firstName。
strName,totalMoney
循环计数器
通常采用字母i,j,k或者counter,index
i,j,k,count,index
包
采用完整的英文描述符,所有单词都小写
com.travelsky.angel
com.travelsky.angel.util
成员函数
采用完整的英文描述说明成员函数功能,第一个单词尽可能采用一个生动的动词,除第一个单词外,每个单词第一个字母大写。
openFile()
addUser()
设置成员函数
被访问字段名的前面加上前缀set。
setName()
setPower()
对于JAVA语言,还有一些约定俗成的命名方式可增加程序的可读性,如:
ØServlet命名为:
****Servlet
ØFilter命名为:
****Filter
Ø消息驱动BEAN命名为:
****MDB
Ø还有如:
****Service,****DAO,****Helper,****DTO等。
6声明
6.1包
在导入包时当完全限制代码所使用的类的名字,尽量少用通配符的方式,但导入一些通用包,或用到一个包下大部分类时,则可是使用通配符方式,如:
importcom.travelsky.angel.flight.QueryService;
importjava.util.*;
同一包中的类导入时当声明在一起,可由编辑器自动完成此功能。
重要的包当添加注释。
6.2类,接口
参照下面的顺序来定义类或接口:
[可见性][abstract|final][Class|Interface]ClassName[extends|implements][ParentClassName|ParentInterfaceName]
6.3方法
良好的程序设计应该尽可能减小类与类之间耦合,所遵循的经验法则是:
尽量限制成员函数的可见性。
如果成员函数没必要公有(public),就定义为保护(protected);没必要保护(protected),就定义为私有(private)。
方法定义语法规范:
[可见性][(abstract|final)][synchronized][返回值类型]method_name(参数列表)[(throws)][异常列表]{
//功能模块
}
若有toString(),equals(),hashCode(),colone()等重载自Object的方法,应将其放在类的最后。
建议声明顺序:
Ø构造方法
Ø静态公共方法
Ø静态私有方法
Ø受保护方法
Ø私有方法
Ø继承自Object的方法
6.4字段
若没有足够理由,不要把实例或类变量声明为公有。
公共和保护的可见性应当尽量避免,所有的字段都建议置为私有,由获取和设置成员函数(Getter、Setter)访问。
不允许“隐藏”字段,即给局部变量所取的名字,不可与另一个更大范围内定义的字段的名字相同(或相似)。
例如,如果把一个字段叫做firstName,就不要再生成一个局部变量叫做firstName,或者任何易混肴的名字,如fistName。
一行代码只声明一个变量,仅将一个变量用于一件事。
建议声明顺序:
Ø常量
Ø类变量
Ø实例变量
Ø公有字段
Ø受保护字段
Ø私有字段
7其它注意事项
7.1表达式和语句
各功能块间以空行相隔。
判断中如有常量,则应将常量置与判断式的右侧。
如:
if(true==isAdmin())...
循环跳转条件当注明清楚。
Exit()除了在main中可以被调用外,其他的地方不应该调用。
在含有多种运算符的表达式中使用圆括号来避免运算符优先级问题
语句应尽可能简单易读,如:
d=(a=b+c)+r;
不如写成:
a=b+c;
d=a+r;
去掉无用的import语句
7.2异常
顶层的main()函数应该截获所有的异常,并且打印(或者记录在日志中)在屏幕上。
通常的思想是只对错误采用异常处理:
逻辑和编程错误,设置错误,被破坏的数据,资源耗尽,等等。
最小化捕获异常的类型。
不使用异常实现控制结构。
若有finally子句,则不要在try块中直接返回,亦不要在finally中直接返回。
如果捕获了异常,则必须去处理它,至少将堆栈打印出来。
7.3日志
日志是代码的重要组成部分,应简单,高效,灵活,日志建议使用common_logging组件,底层可使用javalogger或log4j,在中大型的项目中,代码中尽可能不出现System.out来直接输出信息。
7.4移植性
文件编码尽可能采用UTF-8,底限是项目中的所有文件编码应当一致。
为保证系统的跨平台性,不得使用任何某平台专有/用的资源、类库等。
在代码级也必须同时保证系统的可移植性。
必须在LINUX、WINDOWS下都进行测试,并且保证处理结果的一致性。
不要经常使用synchronized这个关键字,如果你的断点设在这些关键字的作用域内的话,调试的时候你会发现的断点会到处乱跳,让你不知所措。
除非必须,尽量不要使用。
如果需要换行的话,尽量用println来代替在字符串中使用"\n"。
不要这样:
System.out.print("Hello,world!
\n");
要这样:
System.out.println("Hello,world!
");
或
- 配套讲稿:
如PPT文件的首页显示word图标,表示该PPT已包含配套word讲稿。双击word图标可打开word文档。
- 特殊限制:
部分文档作品中含有的国旗、国徽等图片,仅作为作品整体效果示例展示,禁止商用。设计者仅对作品中独创性部分享有著作权。
- 关 键 词:
- Java 编码 指南