JAVA源代码规范.docx
《JAVA源代码规范.docx》由会员分享，可在线阅读，更多相关《JAVA源代码规范.docx（45页珍藏版）》请在冰点文库上搜索。
JAVA源代码规范
JAVA代码规范
（初稿）
2004、4
⏹版本更新信息
本版本创建/修改、维护、批准涉及人员如下：
创建/修改者：
XX
维护者：
XX
批准者：
XX
具体版本更新记录如表1-1：
表1-1版本更新记录
版本号
修改确认日期
修改人
修改位置
修改方式
（AMD）
修改内容概述
V1、0
2004、4
XX
全部
A
初始版本发布
修改方式：
A－增加M－修改D－删除
⏹目得
本文提供一整套编写高效可靠得Java代码得标准、约定与指南。
它们以安全可靠得软件工程原则为基础，使代码易于理解、维护与增强灵活性。
通过遵循一套通用得程序设计标准，显著提高Java软件开发者得生产效率，为开发团队得程序设计带来更大得一致性，使软件开发团队得效率明显提高。
⏹规范得执行
本文档适用于公司内进行软件开发得所有技术人员，即公司内软件开发人员编写得所有源代码都必须遵循本规范。
除临时性项目之外得任何项目均应严格按照此标准执行，“临时性项目”指：
Ø为市场推广目得而编写得示程序
Ø为一次性用途而编写得临时性小程序
为学习目得而编写得测试程序
⏹文档类别
本文档属标准规范类得项目限制级文档，未经总经理及总经理授权人员批准，不得提供公司以外得人员阅读与使用。
⏹版本更新条件
本文档得定期评审时间为每年得1月，评审及修订步骤依据SEPG工作规范规定。
此外，如遇下列条件可进行评审，并根据评审结果决定就是否需要进行修订：
Ø本文档所列得引用得标准已经更新。
Ø本文档得使用者若对本文档有任何评论、建议或意见，请通过企业内部网络发电子邮件给SEPG，所收到得电子邮件将会在评审与修订时给予充分得考虑。
⏹使用对象
本文档得使用对象包括：
Ø项目管理者
Ø质量保证人员
Ø软件开发人员
1介绍
1.1为什么要有编码规范
编码规范对于程序员而言尤为重要，有以下几个原因：
Ø一个软件产品得80%得生命期就是在维护。
Ø几乎没有一个软件在它得整个生命期里都就是被它得作者来维护得。
Ø使用好得风格提高了软件得可维护性。
Ø如果源代码与软件产品就是捆绑给客户得，作为产品得剩余部分，它应该有好得分包（well-packaged），足够清晰与专业得代码。
2通用代码格式
2.1文件组织
一个文件由被空行分割而成得段落以及标识每个段落得可选注释共同组成。
超过2000行得程序难以阅读，应该尽量避免。
Java源文件必须遵循以下规则：
Ø文件头部注释
所有得源文件都应该在开头有一个C语言风格得注释，其中列出文件名、作者、公司、日期、描述、修改说明与版权声明：
/*
*File:
OrderSessionBean、java
*Author:
wangxie
*Version:
1、1
*Date:
06/04/2004
*Modify:
*Description:
*Copyrightnotice
*/
Ø包与引入语句
在Java源文件中，第一个非注释行就是Package语句。
Package 行要在 Import 行之前，Import 中标准得包名要在本地得包名之前，而且按照字母顺序排列。
例如：
packagejava、awt;
importjava、awt、peer、CanvasPeer;
importjava、io、InputStream;
importcn、edu、cuit、TestApplication;
Ø类与接口声明
下表描述了类与接口声明得各个部分以及它们出现得先后次序。
序号
类/接口声明得各部分
注解
1
类/接口文档注释（/**……*/）
该注释中所需包含得信息。
2
类或接口得声明
3
类/接口实现得注释（/*……*/）如果有必要得话
该注释应包含任何有关整个类或接口得信息，而这些信息又不适合作为类/接口文档注释。
4
类得（静态）变量
首先就是类得公共变量，随后就是保护变量，再后就是包一级别得变量（没有访问修饰符，accessmodifier），最后就是私有变量。
5
实例变量
首先就是公共级别得，随后就是保护级别得，再后就是包一级别得（没有访问修饰符），最后就是私有级别得。
6
构造器
7
方法
这些方法应该按功能，而非作用域或访问权限，分组。
例如，一个私有得类方法可以置于两个公有得实例方法之间。
其目得就是为了更便于阅读与理解代码。
2.2缩进
4个空格常被作为缩进排版得一个单位，以表示缩进，显示程序得层次级别，增加程序得可读性。
不要在源代码中保留tab字符，这就是因为tab字符会随着不同用户得不同设置与不同得资源管理工具（打印、文档、版本控制等）而代表不同得宽度。
2.3行长度
尽量避免一行得长度超过80个字符，因为很多终端与工具不能很好处理之。
注意：
用于文档中得例子应该使用更短得行长，长度一般不超过70个字符。
2.4换行
当一个表达式无法容纳在一行内时，可以依据如下一般规则断开之：
Ø在一个逗号后面断开
Ø在一个操作符前面断开
Ø宁可选择较高级别（higher-level）得断开，而非较低级别（lower-level）得断开
Ø新得一行应该与上一行同一级别表达式得开头处对齐
Ø如果以上规则导致您得代码混乱或者使您得代码都堆挤在右边，那就代之以缩进8个空格。
以下就是断开方法调用得一些例子：
someMethod（longExpression1,longExpression2,longExpression3,
longExpression4,longExpression5）;
var=someMethod1（longExpression1,
someMethod2（longExpression2,
longExpression3））;
以下就是两个断开算术表达式得例子。
前者更好，因为断开处位于括号表达式得外边，这就是个较高级别得断开。
longName1=longName2*（longName3+longName4-longName5）
+4*longname6;//PREFFER
longName1=longName2*（longName3+longName4
-longName5）+4*longname6;//AVOID
以下就是两个缩进方法声明得例子。
前者就是常规情形。
后者若使用常规得缩进方式将会使第二行与第三行移得很靠右，所以代之以缩进8个空格
//CONVENTIONALINDENTATION
someMethod（intanArg,ObjectanotherArg,StringyetAnotherArg,
ObjectandStillAnother）{
、、、
}
//INDENT8SPACESTOAVOIDVERYDEEPINDENTS
privatestaticsynchronizedhorkingLongMethodName（intanArg,
ObjectanotherArg,StringyetAnotherArg,
ObjectandStillAnother）{
、、、
}
if语句得换行通常使用8个空格得规则，因为常规缩进（4个空格）会使语句体瞧起来比较费劲。
比如：
//不要使用如下缩进
if（（condition1&&condition2）
||（condition3&&condition4）
||!
（condition5&&condition6））{//不好得换行
doSomethingAboutIt（）;//易使这行被忽视
}
//使用如下缩进
if（（condition1&&condition2）
||（condition3&&condition4）
||!
（condition5&&condition6））{
doSomethingAboutIt（）;
}
//或者使用如下缩进
if（（condition1&&condition2）||（condition3&&condition4）
||!
（condition5&&condition6））{
doSomethingAboutIt（）;
}
这里有三种可行得方法用于处理三元运算表达式：
alpha=（aLongBooleanExpression）?
beta:
gamma;
alpha=（aLongBooleanExpression）?
beta
:
gamma;
alpha=（aLongBooleanExpression）
?
beta
:
gamma;
2.5空行
空行将逻辑相关得代码段分隔开，以提高可读性。
下列情况应该总就是使用两个空行：
Ø一个源文件得两个片段（section）之间
Ø类声明与接口声明之间
下列情况应该总就是使用一个空行：
Ø两个方法之间
Ø方法内得局部变量与方法得第一条语句之间
Ø块注释或单行注释之前
Ø一个方法内得两个逻辑段之间，用以提高可读性
2.6空格
下列情况应该使用空格：
Ø一个紧跟着括号得关键字应该被空格分开，例如：
while（true）{
、、、
}
注意：
空格不应该置于方法名与其左括号之间。
这将有助于区分关键字与方法调用。
Ø空白应该位于参数列表中逗号得后面
Ø所有得二元运算符，除了"、"，应该使用空格将之与操作数分开。
一元操作符与操作数之间不因该加空格，比如：
负号（"-"）、自增（"++"）与自减（"--"）。
例如：
a+=c+d;
a=（a+b）/（c*d）;
while（d++=s++）{
n++;
}
printSize（"sizeis"+foo+"\n"）;
Øfor语句中得表达式应该被空格分开，例如：
for（expr1;expr2;expr3）
Ø强制转型后应该跟一个空格，例如：
myMethod（（byte）aNum,（Object）x）;
myMethod（（int）（cp+5）,（（int）（i+3））+1）;
2.7注释
Java程序有两类注释：
实现注释（implementationcomments）与文档注释（documentcomments）。
实现注释就是那些在C++中见过得，使用/*、、、*/与//界定得注释。
文档注释（被称为"doccomments"）就是Java独有得，并由/**、、、*/界定。
文档注释可以通过javadoc工具转换成HTML文件。
注意：
频繁得注释有时反映出代码得低质量。
当您觉得被迫要加注释得时候，考虑一下重写代码使其更清晰。
2.7.1注释约定
Ø注释应该增加代码得清晰度。
代码注释得目得就是要使代码更易于被同时参与程序设计得开发人员以及其她后继开发人员理解。
Ø避免使用装饰性内容，也就就是说，不要使用象广告横幅那样得注释语句。
典型得就是用星号将她们得内部注释圈起来。
这只就是在大量浪费时间，并不能给最终得产品增加丝毫价值。
Ø保持注释得简洁。
最好得注释应该就是简单明了得注释。
注释不必洋洋洒洒，只需提供足够得信息，使别人能够理解您得代码。
Ø先写注释，后写代码。
写代码注释得最好方法就是在写代码之前就写注释。
这使您在写代码之前可以想想代码得功能与运行。
而且这样确保不会遗漏注释。
另一种方法就是边写代码边写注释。
因为注释可以使代码更易理解，所以在程序开发得过程中，也可以利用这一点。
如果打算花些时间写注释，那么至少您应从这个过程中获得些什么。
Ø注释信息不仅要包括代码得功能，还应给出原因。
例如，下面例子中得代码显示金额在$1,000以上（包括$1,000）得定单可给予5%得折扣。
为什么要这样做呢？
难道有一个商业法则规定大额定单可以得到折扣吗？
这种给大额定单得特殊就是有时限得呢，还就是一直都这样？
最初得程序设计者就是否只就是由于慷慨大度才这样做呢？
除非它们在某个地方（或者就是在源代码本身，或者就是在一个外部文档里）被注释出来，否则您不可能知道这些。
例：
if（grandTotal>=1000、00）{
grandTotal=grandTotal*0、95;
}
2.7.2实现注释得格式
程序可以有4种实现注释得风格：
块（block）、单行（single-line）、尾端（trailing）与行末（end-of-line）。
Ø块注释
块注释通常用于提供对文件，方法，数据结构与算法得描述。
块注释被置于每个文件得开始处以及每个方法之前。
它们也可以被用于其她地方，比如方法内部。
在功能与方法内部得块注释应该与它们所描述得代码具有一样得缩进格式。
块注释之首应该有一个空行，用于把块注释与代码分割开来，比如：
/*
*Hereisablockcomment、
*/
块注释可以以/*-开头，这样indent
（1）就可以将之识别为一个代码块得开始，而不会重排它。
/*-
*Hereisablockcommentwithsomeveryspecial
*formattingthatIwantindent
（1）toignore、
*
*one
*two
*three
*/
Ø单行注释
短注释可以显示在一行内，并与其后得代码具有一样得缩进层级。
如果一个注释不能在一行内写完，就该采用块注释（参见"块注释"）。
单行注释之前应该有一个空行。
以下就是一个Java代码中单行注释得例子：
if（condition）{
/*Handlethecondition、*/
、、、
}
Ø尾端注释
极短得注释可以与它们所要描述得代码位于同一行，但就是应该有足够得空白来分开代码与注释。
若有多个短注释出现于大段代码中，它们应该具有相同得缩进。
以下就是一个Java代码中尾端注释得例子：
if（a==2）{
returnTRUE;/*specialcase*/
}else{
returnisPrime（a）;/*worksonlyforodda*/
}
Ø行末注释
注释界定符"//"，可以注释掉整行或者一行中得一部分。
它一般不用于连续多行得注释文本；然而，它可以用来注释掉连续多行得代码段。
以下就是所有三种风格得例子：
if（foo>1）{
//Doadouble-flip、
、、、
}
else{
returnfalse;//Explainwhyhere、
}
//if（bar>1）{
//
////Doatriple-flip、
//、、、
//}
//else{
//returnfalse;
//}
2.7.3文档注释
文档注释描述Java得类、接口、构造器，方法，以及字段（field）。
每个文档注释都会被置于注释定界符/**、、、*/之中，一个注释对应一个类、接口或成员。
该注释应位于声明之前：
/**
*TheExampleclassprovides、、、
*/
publicclassExample{、、、
注意顶层（top-level）得类与接口就是不缩进得，而其成员就是缩进得。
描述类与接口得文档注释得第一行（/**）不需缩进；随后得文档注释每行都缩进1格（使星号纵向对齐）。
成员，包括构造函数在内，其文档注释得第一行缩进4格，随后每行都缩进5格。
若您想给出有关类、接口、变量或方法得信息，而这些信息又不适合写在文档中，则可使用实现块注释或紧跟在声明后面得单行注释。
例如，有关一个类实现得细节，应放入紧跟在类声明后面得实现块注释中，而不就是放在文档注释中。
文档注释不能放在一个方法或构造器得定义块中，因为Java会将位于文档注释之后得第一个声明与其相关联。
2.7.4快速浏览javadoc
javadoc得程序可以处理Java得源代码文件，并且为Java程序产生HTML文件形式得外部注释文档。
Javadoc支持一定数目得标记，标识注释文档中各段起始位置得保留字。
详情请参考J2SDKjavadoc文档。
标记
用于
目得
@authorname
类、
接口
说明特定某一段程序代码得作者。
每一个作者各有一个标记。
@deprecated
类、
成员函数
说明该类得应用程序编程接口（API）已被废弃，因此应不再使用。
@exceptionnamedescription
成员函数
说明由成员函数发出得异常。
一个异常采用一个标记，并要给出异常得完整类名。
@paramnamedescription
成员函数
用来说明传递给一个成员函数得参数，其中包括参数得类型/类与用法。
每个参数各有一个标记。
@returndescription
成员函数
若成员函数有返回值，对该返回值进行说明。
应说明返回值得类型/类与可能得用途。
@since
类、成员函数
说明自从有JDK1、1以来，该项已存在了多长时间。
@seeClassName
类、接口、成员函数、字段
在文档中生成指向特定类得超文本链接。
可以并且应该采用完全合法得类名。
@seeClassName#memberfunctionName
类、接口、成员函数、字段
在文档中生成指向特定成员函数得超文本链接。
可以并且应该采用完全合法得类名。
@versiontext
类、接口
说明特定一段代码得版本信息。
2.8声明
2.8.1每行声明变量得数量
推荐一行一个声明，因为这样以利于写注释。
亦即，
intlevel;//indentationlevel
intsize;//sizeoftable
要优于，
intlevel,size;
不要将不同类型变量得声明放在同一行，例如：
intfoo,fooarray[];//避免！
注意：
上面得例子中，在类型与标识符之间放了一个空格
2.8.2初始化
在声明局部变量得同时初始化。
唯一不这么做得理由就是变量得初始值依赖于某些先前发生得计算。
2.8.3布局
只在代码块得开始处声明变量。
（一个块就是指任何被包含在一对大括号"{"与"}"中间得代码。
）不要在首次用到该变量时才声明之。
这会把注意力不集中得程序员搞糊涂，同时会妨碍代码在该作用域内得可移植性。
voidmyMethod（）{
intint1=0;//在方法得开始处
if（condition）{
intint2=0;//在”if”块得开始处
、、、
}
}
该规则得一个例外就是for循环得索引变量
for（inti=0;i避免声明得局部变量覆盖上一级声明得变量。
例如，不要在内部代码块中声明相同得变量名：
intcount;
、、、
myMethod（）{
if（condition）{
intcount=0;//避免！
、、、
}
、、、
}
2.8.4类与接口得声明
当编写类与接口时，应该遵守以下格式规则：
Ø在方法名与其参数列表之前得左括号"（"间不要有空格。
Ø左大括号"{"位于声明语句同行得末尾。
Ø右大括号"}"另起一行，与相应得声明语句对齐，除非就是一个空语句，"}"应紧跟在"{"之后。
classSampleextendsObject{
intivar1;
intivar2;
Sample（inti,intj）{
ivar1=i;
ivar2=j;
}
intemptyMethod（）{}
、、、
}
2.9语句
2.9.1简单语句
每行至多包含一条语句，例如：
argv++;//正确
argc--;//正确
argv++;argc--;//避免！
2.9.2复合语句
复合语句就是包含在大括号中得语句序列，形如"{语句}"。
例如下面各段。
Ø大括号中得语句应该较之复合语句缩进一个层次。
Ø左大括号"{"应位于复合语句起始行得行尾；右大括号"}"应另起一行并与复合语句首行对齐。
。
Ø大括号可以被用于所有语句，包括单个语句，只要这些语句就是诸如if-else或for控制结构得一部分。
这样便于添加语句而无需担心由于忘了加括号而引入bug。
2.9.3返回语句
一个带返回值得return语句不使用小括号"（）"，除非它们以某种方式使返回值更为显见。
例如：
return;
returnmyDisk、size（）;
return（size?
size:
defaultSize）;
2.9.4if，if-else，ifelse-ifelse语句
if-else语句应该具有如下格式：
if（condition）{
statements;
}
if（condition）{
statements;
}else{
statements;
}
if（condition）{
statements;
}elseif（condition）{
statements;
}else{
statements;
}
注意：
if语句总就是用"{"与"}"括起来，避免使用如下容易引起错误得格式：
if（condition）//避免！
省略{}!
statement;
2.9.5for语句
一个for语句应该具有如下格式：
for（initialization;condition;update）{
statements;
}
一个空得for语句（所有工作都在初始化，条件判断，更新子句中完成）应该具有如下格式：
for（initialization;condition;update）;
当在for语句得初始化或更新子句中使用逗号时，避免因使用三个以上变量，而导致复杂度提高。
若需要，可以在for循环之前（为初始化子句）或for循环末尾（为更新子句）使用单独得语句。
2.9.6while语句
一个while语句应该具有如下格式
while（condition）{
statements;
}
一个空得while语句应该具有如下格式：
while（condition）;
2.9.7do-while语句
一个do-while语句应该具有如下格式：
do{
statements;
}while（condition）;
2.9.8switch语
升级会员 