JAVA编程规约.docx
《JAVA编程规约.docx》由会员分享，可在线阅读，更多相关《JAVA编程规约.docx（29页珍藏版）》请在冰豆网上搜索。
JAVA编程规约
Java编程规约
1．引言∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙2
2．文件名∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙2
3．文件组织∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙2
4．缩进格式∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙5
5．注释∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙7
6．声明∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙12
7．语句∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙14
8．空白∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙17
9．命名规范∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙19
10．编程惯例∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙20
11．Log∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙22
12．代码示例∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙∙24
1–引言
1.1为什么需要编码规范
编码规范对编程人员来说重要性有很多理由：
∙一个软件的生命周期中有百分之八十的时间是在维护。
∙几乎没有哪个软件是完全由它的原担当来进行维护的。
∙编码规范可以提高代码的可读性，可以让其他人员理解得更快，更清晰。
∙在开发产品的时候，需要保持所有产品之间的风格一致性。
2–文件名
2.1文件名后缀
文件类型
后缀
Javasource
.java
Javaclass
.class
3–文件组织
每个文件的组成部分应该以空行和适当的注释分开。
一个文件超过2000行会变得冗长，应该尽量避免。
3.1Java程序文件
每个Java程序应该包括单个public的class或者interface。
当私有的classes与interface与一个公有的class关联的时候，你应该将它们放在同一个文件中作为公有的class。
公有的class应该是文件的第一个class或interface。
Java文件有着以下的组织顺序
∙文件头注释
∙包与导入类声明
∙类与接口声明
3.1.1文件头注释
所有的程序文件应该以注释开始，该注释列出类名，版本信息，日期，以及版权等。
每个项目应该统一起来，格式要一致。
//*********************************************************************
//系统名称：
XXXXXXXX
//模块名称：
XXXXXXXX
//版本信息：
//版本日期作者备注
//1.12008/02/20張三 新規作成
//1.12008/02/21張三 XXXXXXXX
//*********************************************************************
3.1.2包与导入类
第一个无注释行是一个包声明，在这之后是导入类声明，如：
packagejava.awt;
importjava.awt.peer.CanvasPeer;
注：
包名应该全部是小写的字母，一般的应该以最高的域名如：
com,edu,gov,mil,net,org,或以两个字母标识的国家名字开始。
或者以项目的名字开始。
在导入类的时候，注意不要用importjava.awt.*;的类似方法，要一个一个class具体导入，并且按照字母顺序排列，不同package中或功能的class要以一空行隔开。
这样别人阅读程序的时候能够快速知道并定位到相关的class。
如：
packagecscweb.preserve.model;
importjava.util.ArrayList;
importorg.apache.log4j.Category;
importmon.ejb.CSCWebException;
importmon.ejb.PJCodeBook;
importcscweb.util.DateUtil;
importcscweb.util.MessageManager;
importcscweb.preserve.data.HozenActionDefMasterData;
importcscweb.preserve.ejb.PreserveDefReg;
importcscweb.preserve.ejb.PreserveDefRegHome;
注：
若使用eclipse可通过快捷键ctrl+shift+o完成。
3.1.3类与接口声明
下面这个表格描述了一个类或接口的组成成员定义，并按规定的顺序排列，具体实例请见（Java代码实例）
类/接口组成
备注
1
类/接口文档注释
就是一些功能说明以及作者版本等等
2
类或接口声明
3
类/接口的执行注释（可选）
这个注释应该包含所有不适合这个类或接口范围的信息
4
类静态（static）变量
首先是公有（public）类变量，然后是保护变量（protected）,接着是package内可访问变量（无范围修饰符）,最后是私有变量（private）。
5
实例变量
顺序同上
6
构造函数
7
方法
方法应该以功能进行组合，而不应该以可访问范围进行分类组合。
比如：
一个私有的方法可以在两个公有的方法之间，目的是为了使程序更易读好懂。
4–缩排格式
每个缩进单元应该是四个空格，到底是用空格或TAB来进行缩排并未明确指定。
但是建议用TAB键来进行缩进。
文件中不要一会儿用空格一会儿用TAB键，TAB键要设成四个空格的宽度。
4.1行宽
每行避免超过80个字符，因为有的终端和编辑工具不能很好的处理超过80字符的行。
4.2换行
当一个表达语句一行不适合的时候，应该用以下的原则进行分行：
∙在逗号之后
∙在一个操作符之前
∙在优先度高的地方
∙新行的开始应该与上一行同一级别的地方对齐。
∙如果满足以上的原则的新行的开始比较靠右，应该用8个空格进行缩排。
下面是两个调用方法换行例子：
someMethod（longExpression1,longExpression2,longExpression3,
longExpression4,longExpression5）;
var=someMethod1（longExpression1,
someMethod2（longExpression2,
longExpression3））;
下面是两个算术运算换行的例子。
第一个是建议使用的，因为换行在括号的外面，满足优先度高的原则。
longName1=longName2*（longName3+longName4-longName5）
+4*longname6;//推荐
longName1=longName2*（longName3+longName4
-longName5）+4*longname6;//禁止
下面是两个方法声明缩排的例子。
第一个是常规情况。
第二种情况就是应该用8个空格进行缩排的情况。
//CONVENTIONALINDENTATION
someMethod（intanArg,ObjectanotherArg,StringyetAnotherArg,
ObjectandStillAnother）{
...
}
//INDENT8SPACESTOAVOIDVERYDEEPINDENTS
privatestaticsynchronizedhorkingLongMethodName（intanArg,
ObjectanotherArg,StringyetAnotherArg,
ObjectandStillAnother）{
...
}
条件语句需要换行的例子：
//DON'TUSETHISINDENTATION
if（（condition1&&condition2）
||（condition3&&condition4）
||!
（condition5&&condition6））{//BADWRAPS
doSomethingAboutIt（）;//MAKETHISLINEEASYTOMISS
}
//USETHISINDENTATIONINSTEAD
if（（condition1&&condition2）
||（condition3&&condition4）
||!
（condition5&&condition6））{
doSomethingAboutIt（）;
}
//ORUSETHIS
if（（condition1&&condition2）||（condition3&&condition4）
||!
（condition5&&condition6））{
doSomethingAboutIt（）;
}
下面是三个使用三重表达式的例子：
alpha=（aLongBooleanExpression）?
beta:
gamma;
alpha=（aLongBooleanExpression）?
beta
:
gamma;
alpha=（aLongBooleanExpression）
?
beta
:
gamma;
5–注释
Java程序有两种注释：
代码注释（implementationcomments）与文档注释（documentationcomments）。
代码注释类似于C++，用/*…*/以及//。
文档注释为Java独有的，用/**…*/，文档注释能够用javadoc工具生成HTML形式的文档。
代码注释用于一段代码的执行说明，而文档注释用于程序的总括描述，比如一个类，方法或变量的功能描述，这些描述可以通过javadoc进行浏览，即使在没有代码的情况下。
注释应该能够给予代码概要的描述，并且能够提供直接阅读代码本身所不能得到的信息。
注释应仅仅包含便于阅读和理解程序的信息。
比如对于包名与文件目录应该对应起来这种就不应该需要用注释来说明。
另外代码注释也不应该重复使用，随着代码的改修，注释也就有可能会”过期”，因此在代码修改的同时不要忘了将注释也同时更新。
注:
1.注释往往关系到代码的品质，写注释的时候也要注意写得更清晰一点。
2.注释也不应该用大的框框包围起来，比如用*号或其它的字符画的框框。
3.注释不应该含有特殊的字符，比如退格键等。
5.1代码注释格式
程序代码注释有四种方式:
块（block）,单行（single-line）,（trailing）,行尾（end-of-line）。
5.1.1块注释
块注释用在文件，方法，数据结构以及运算法则等方面的描述。
块注释应该在每个文件的开头以及每个方法的前面。
当然也可以用在方法的里面，但是一定要与代码的缩排一致。
块注释也应该与前面代码之间有一空行。
/*
*Hereisablockcomment.
*/
块注释可以以/*-开头，当indent
（1）碰到它的时间，将不会对它重新格式化，如：
/*-
*Hereisablockcommentwithsomeveryspecial
*formattingthatIwantindent
（1）toignore.
*
*one
*two
*three
*/
注:
如果你不用indent
（1）,你就用不着用/*-或为了防止别人在你的程序上用indent
（1）而作出让步。
5.1.2单行注释
短的说明可以用一行注释并且要与代码缩排一致对齐，如果一行注释写不下就得用前面所说的块注释方法。
（参见5.1.1）单行前面一般得要有一空行，下面是一个单行注释的例子。
if（condition）{
/*Handlethecondition.*/
...
}
5.1.3TrailingComments
很短的注释可以跟代码在同一行上，但必须跟代码有足够的距离，如果在一块代码中有许多这样的注释，它们必须用tab键设置来进行缩排对齐，如下例：
if（a==2）{
returnTRUE;/*specialcase*/
}else{
returnisPrime（a）;/*worksonlyforodda*/
}
5.1.4行尾注释
用//来注释代码，可以注释一整行，也可以仅仅注释一行的一部分。
它不应该用在注释连续多行的文本说明，但可以用来注释连续多行代码，下面是三个不同样式的例子：
if（foo>1）{
//Doadouble-flip.
...
}
else{
returnfalse;//Explainwhyhere.
}
//if（bar>1）{
//
////Doatriple-flip.
//...
//}
//else{
//returnfalse;
//}
5.2文档注释
先给个简单的例子：
/**
*ProcessanHTTPrequest.
*
*@paramrequestTheservletrequestweareprocessing
*@paramresponseTheservletresponsewearecreating
*
*@returntrueiftheprocessissuccessful
*falseiftheprocessisfailed
*
*@exceptionIOExceptionifaninput/outputerroroccurs
*@exceptionServletExceptionifaservletexceptionoccurs
*/
protectedbooleanprocess（HttpServletRequestrequest,
HttpServletResponseresponse）
throwsIOException,ServletException{
}
可以看到方法说明，和下面的标签（TAG）有一空行，不同的标签之间应该空一行。
常用的标签也就是上面所看到三个，@param指方法参数，@return指方法的返回值，@exception指方法可能会抛出的例外。
更详细的说明请参照"HowtoWriteDocCommentsforJavadoc"，它包括文档注释的标签使用（@return,@param,@see）:
文档注释描述Javaclasses,interfaces,constructors,methods,以及fields.每个文档注释用/**...*/进行分割,每个类，接口，或方法都有一个注释，这种注释得在声明之前：
/**
*TheExampleclassprovides...
*/
publicclassExample{...
注意的是处在最顶层的类和接口不用缩进。
文档注释的第一行（/**）跟所有注释的代码对齐，后面的*多缩进一个空格（*号对齐）。
文档注释不应该用在方法或构造函数的内部，因为Java只会关联第一个声明之前的文档注释与这个声明。
5.3维护注释
在项目后期维护的时候，特别是维护别担当程序，必须要加上必要的注释，一般有以下几种情况：
∙单行修改：
//modifiedbyusernameonyyyy/mm/ddfor指摘票名
//rec.setDeleteFlg（CodeBook.DELETE）; //old
rec.setDeleteFlg（CodeBook.NO_DELETE）; //new
∙多行修改
/*commentedbyusernameonyyyy/mm/ddfor指摘票名
doInit（）;
...
*/
//addedbyusernameonyyyy/mm/ddfor指摘票名
doNewInit（）;
...
//endofadded
∙如果是变更比较大的场合，需要在版本信息一栏注上说明，如：
参照：
3.1.1文件头注释的履历。
6–声明
6.1每行声明数
建议一行只有一个声明，也便于注释。
换句话说也就是
intlevel;//indentationlevel
intsize;//sizeoftable
比下面优先使用
intlevel,size;
更不要将不同类型的声明放在同一行，例：
intfoo,fooarray[];//WRONG!
注:
上面的这个例子在类型和变量之间用了空格，另一个可选的方法是用tab健，如：
intlevel;//indentationlevel
intsize;//sizeoftable
ObjectcurrentEntry;//currentlyselectedtableentry
6.2初期化
尽量在声明的地方进行初期化，不过当变量需要根据后面的计算来进行赋值的时候也可不要进行初期化。
6.3声明点
最好将声明摆在每一块的开始。
（一块一般指是用{}围起来的一段代码）不要等到变量第一次使用的时候再去初期化，它有可能会使粗心的程序员迷惑或使这段范围内的代码降低了灵活性。
voidmyMethod（）{
intint1=0;//beginningofmethodblock
if（condition）{
intint2=0;//beginningof"if"block
...
}
}
有一个例外就是在for循环体中可以定义索引：
for（inti=0;i不要在块内部定义与外部相同名字的变量，比如：
intcount;
...
myMethod（）{
if（condition）{
intcount=0;//AVOID!
...
}
...
}
6.4类与接口声明
当编写Java类与接口的时候，下面一些规则得要遵守：
∙在方法名字与后面的圆括号"（"之间以及圆括号与后面的参数列表之间都不应该有空格。
∙起始大括号"{"应该出现在跟声明同一行上，且与前面有一空格。
∙结束大括号"}"应该另起一行，并且与开始大括号相匹配对应，不过当语句为null时例外，应该在"{"立马用"}"来结束，例：
classSampleextendsObject{
intivar1;
intivar2;
Sample（inti,intj）{
ivar1=i;
ivar2=j;
}
intemptyMethod（）{}
...
}
∙方法之间应该用一空行分隔开
7–语句
7.1简单语句
每行至多一个语句，例:
argv++;//Correct
arg
升级会员 