JAVA编码规约.docx
《JAVA编码规约.docx》由会员分享，可在线阅读，更多相关《JAVA编码规约.docx（20页珍藏版）》请在冰豆网上搜索。
JAVA编码规约
JAVA编码规约
1、介绍
1．1为什么要有代码惯例
代码惯例之所以重要有以下几点原因：
软件寿命价值的80%是维护。
几乎没有软件在整个使用过程中都有由原作者维护。
代码惯例增加了软件包的可读性，使工程师们能更快、更完整地理解新软件。
如果你想把你的原始代码变成产品，你需要确认它是否和你生产的其它产品一样有好的包装。
1．2确认
这个文件在SUN公司的JAVA语言说明书中反映了JAVA语言编码标准。
这方面规定主要来自PeterKing,PatrickNaughton,JonniKanerva,andScottHommel.
关于这个文档的改写、修改或再分配的问题，请看版权公告。
对于这个文档的建议请发贴自alans@
2------文件名
这一节列举了常用的文件后缀与名称。
2．1文件后缀
JAVA使用以下后缀：
文件种类
后缀
JAVAsource
.java
JAVAbytecode
.class
2．2普通文档名称
通常用的文档名称
文档名称
使用
GNUmakefile
makefile最恰当的名字。
我们使用gnumake制造我们的软件。
Readme
概括特定目录内容的文档的最恰当名称。
3.文件的组织结构
一个文件应当由多个被分隔的段组成，并由空行和可选择注释来识别。
超过2000行的文件由于冗长而应当避免。
Java程序的正确格式可参看第19页的范例“Java源文件范例”。
3．1Java源文件
每一个Java源文件包含一个单一的公共类或界面。
当私有类或界面与一个公共类发生联系时，你可以将它们以一个公共类放入同一个源文件。
公共类应当是文件中的第一类或界面。
Java源文件有如下次序：
起始注释（参看第4页“起始注释”）
组件和导入语句
类和界面声明（参看第4页“类和界面声明”）
3．1．1起始注释
所有源文件应当以C格式注释开始，并列出类名，版本信息，时间和版权说明：
/*
*类名
*
*版本信息
*
*时间
*
*版权说明
*/
3．1．2组件和导入语句
对于大部分Java源文件而言，第一个无注释行是组件语句。
之后，紧跟着是导入语句。
举例如下：
组件java.awt;
导入java.awt.peer.CanvasPeer
注释：
对于唯一的组件名，第一部分总是小写的ASCII码格式的文本文件，并且是最高级别的域名之一。
目前可用com,edu,gov,mil,net或ISO3166标准（1981）中规定的用于识别国家的英文两个字母的模式。
3．1．3类和界面声明
下表按出现的先后顺序描述了一个类或界面说明的各部分。
参见第19页“java源文件范例”中一个包含注释的示例。
类/界面声明的各部分
注释
1
类/界面文档注释（/**…*/）
参看第9页“文挡注释”中注释的具体内容
2
类或界面语句
3
类/界面补充注释（/*…*/），如果必要的话
这一注释应包含任一类宽或界面宽度的信息，它不适合于类/界面文档注释。
4
类（静态的）变量
首先是公共类变量，其次是保护类，然后是组件级（无访问修改权），最后是私有类。
5
实例变量
首先是公共类，其次是保护类，然后是组建级（无访问修改权），最后是私有类。
6
构成
7
过程
这些过程应当以功能而非作用域和可访问性来分组。
举例说明，一个私有类变量过程可在两个公共实例过程中。
其目的是使读和理解代码更为容易。
4、缩进格式
四个空格作为一个缩进单位。
确切的缩进格式结构（空格符与制表符）未被规范。
表格的设置必须在每8个空格后（而非4个）。
4．1行的长度
由于难于被大多数终端和工具进行处理，应当避免一行超过80个字符。
注释：
在文档中所列举的范例其行的长度应稍短些，一般不超过70个字符。
4．2绕回行
当表达式一行无法写完时，使用以下一般规则进行中断：
在逗号后中断。
在一个运算符前中断。
优先选择高级中断指令。
新行起始表达式的位置应与旧行表达式的位置对齐。
如果上述规则导致代码混乱或编码时顶到了右边界，以8个空格代替。
以下是几个中断程序的调用范例：
someMethod（longExpression1,longExpression2,longExpression3,
longExpression4,longExpression5）;
var=someMethod1（longExpression1,
someMethod2（longExpression2,
longExpression3）;
以下是两个关于中断算术表达式的例子。
第一个例子由于中断发生在插入表达式以外，因而选择了高级中断指令。
longName1=longName2*（longName3+longName4–longName5）
+4*longname6;//PREFER
longName1=longName2*（longName3+longName4
longName5）+4*longname6;//AVOID
以下是两个关于缩进程序的说明。
第一个例子是常规情况。
第二个例子如果采用常规缩进方式，第二和第三行在换行时必然顶至最右，取而代之应空8格。
//常规的缩进方式
someMethod（intanArg,ObjectanotherArg,StringyetAnotherArg,
ObjectandStillAnother）
。
。
。
//缩8个空格以避免更深的锁进
privatestaticsynchronizedhorkingLongMethodName（intanArg,
ObjectanotherArg,StringyetAnotherArg,
ObjectandStillAnother）
。
。
。
由于常规的4空格缩进方式使得体看上去过于复杂，对于语句的绕回行我们一般采用8空格缩进方式。
举例如下：
//不要使用这种缩进方式
if（（condition1&&condition2）
（condition3&&condition4）
!
（condition5&&condition6））//BADWRAPS
doSomethingAboutIt（）;//MAKETHISLINEEASYTOMISS
//取而带之使用这种缩进方式
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;
5注释
JAVA程序可以有二种类型的注释：
执行注解和文件注释。
执行注释是建立在C++之上的，以/*…*/为分隔符的注释；文件注释（即通常所说的doccomment）是一种纯JAVA注释，以/**…*/为分隔符。
Doccomment（文件注释）能够通过JAVADOCA工具被摘录成HEML文件。
执行注释是指为代码注解释，或为特别执行注解释。
Doc注释旨在从一个自由执行的程序描述代码的规范，对于软件开发者来说，手边不再需要源代码就可以阅读。
注释通常用于对代码做总的描述，同时提供附加的信息，这从代码本身来看是不容易得到的。
其包含的信息只与阅读、理解该程序有关，例如：
一个相应组件如何被建立的信息或驻足在何地址录下的信息都将被包含在一个注解中。
对于重要的、非显而易见的设计决定的讨论是适当的，但是应该避免重复信息在代码中出现。
而对于多余注释，则很容易成为过时的。
总的说来，应当避免把过时的注释做为编码的进展。
注意：
经常出现的注释有时反映编码质量的低下。
当你觉得不得不添加注释时，建议你最好重新编写，使得编码更清晰。
注释不能以星号或是其它字符为标识被附在一个大的逻辑单元内。
注释也不能包括特殊字符例如form-feed和backspace。
5.1执行注释的格式
程序可以有四种注释风格：
块、单行、跟踪和行尾。
5.1.1块注释
块注释用于提供文件的描述、方法、数据结构和运算法则。
块注释用于每个文件的开始和方法之前。
也可以用在其他地方，比如用在方法中。
在一个函数或方法中的块注释，应和他们描述的代码排列到同一级别上。
块注释应设置在一个空行的开始。
/*
*Hereisablockcomment.
*/
块注释以/*开始，并且单独领导一行，缩进一格作为块注释的开始，这已经是约定俗成的，不需要另外重新定义格式。
例如：
/*-
*Hereisablockcommentwithsomeveryspecial
*formattingthatIwantindent
（1）toignore.
*
*one
*two
*three
*/
Note:
Ifyoudon'tuseindent
（1）,youdon'thavetouse/*-inyourcodeormakeanyotherconcessionstothepossibilitythatsomeoneelsemightrunindent
（1）onyourcode.
5.1.2单行注释
简短的注释可以出现在单行上，和其描述的代码在同一级别上。
单行注释应遵循块注释的格式。
单行注释应单起一行。
例如：
if（condition）{
/*Handlethecondition.*/
...
}
5.1.3跟踪注释
简短的注释可以和其所描述的代码放到同一行上。
但应和代码保持足够远的空间。
如果不只一个简短的注释出现在大块的代码段中，它们应有同样的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文件注释
文件注释描述Java类、界面、容器、方法和域，每一个文件注释都放在注释界定符/**...*/之间。
注释应在声明之前。
/**
*TheExampleclassprovides...
*/
publicclassExample{...
注意顶级类和界面不缩进，子类和界面则要缩进。
类和界面的第一行文件注释不缩进，后面的注释行有有一个空格的缩进。
子类，包括容器，有4个空格和五个空格的缩进。
如果你需要给出关于类、界面,变量,或方法的信息，这些信息以文件的方式给出是不适当的，那麽你可以直接的在声明之后使用执行块注释或单行注释。
例如，类执行的细节信息应放进执行块注释中，并跟在类语句之后，而不是放在类的文件注释中。
文件注释不应该放到方法或容器的定义块中，因为Java将文件注释和第一个注释之后的声明发生联系。
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
...
}
}
在Java中，for循环中的指针可以在for语句中声明，例如
for（inti=0;i避免在更高层的声明当中隐含局部声明，例如，不要在一个内部块中声明有相同名字的变量。
intcount;
...
myMethod（）{
if（condition）{
intcount=0;//AVOID!
...
}
...
}
6.4声明类和界面
当在译码java的类和界面的时候，应遵循以下的格式化规则：
列出参数时，在方法名和圆括号之间不应该有空格。
"{"出现在声明语句同一行的结尾。
"}"单起一行，但要和最近的“{”匹配。
但如果是空语句则例外。
classSampleextendsObject{
intivar1;
intivar2;
Sample（inti,intj）{
ivar1=i;
ivar2=j;
}
intemptyMethod（）{}
...
}
Methods
7、语句
7．1简单语句
每行最多只能包括一个语句。
比如：
argv++;//Correct
argc--;//Correct
argv++;//argc--;//AVOID
7．2复合语句
复合语句是包括一系列包含在括号{statement}中的语句。
请看以下例子：
被包含的语句必须比复合语句缩进一格。
开始的括号必须在开始复合语句的那一行的末尾；关闭的括号应该重起一行并相对复合语句的开头来说缩进。
当括号是控制结构的一部分时，它们在所有语句中使用，像if-elsea或for语句即便是简要语句。
这使得增加语句非常容易，您也不必为了忘记加括号而付出艰辛的劳动。
7.3return语句
在某种程度上，如果一个return语句的返回值并不非常明显，那么不应该加圆括号。
例如：
return;
returnmyDisk.size（）;
return（size?
size:
defaultSize）;
7.4if,if-else,ifelse-ifelse语句
if-else语句可以分为以下几类：
if（condition）{
statements;
}
if（condition）{
statements;
}else{
statements;
}
if（condition）{
statements;
}elseif（condition）{
statements;
}else{
statements;
}
Note:
ifstatementsalwaysusebraces{}.Avoidthefollowingerror-proneform:
if（condition）//AVOID!
THISOMITSTHEBRACES{}!
statement;
7.5for语句
For语句的形式如下所示：
for（initialization;condition;update）{
statements;
}
一条空的for语句的形式如下所示：
for（initialization;condition;update）;
当在初始化或更新子句的时，避免使用超过三个以上的变量，如果有必要的话，可以在for循环开始之前或结束后使用个别的语句。
7.6while语句
while语句的形式如下所示：
while（condition）{
statements;
}
一个空的while语句的形式如下：
while（condition）;
7.7do-while语句
do-while语句的形式如下：
do{
statements;
}while（condition）;
7.8switch语句
switch（condition）{
caseABC:
statements;
/*fallsthrough*/
caseDEF:
statements;
break;
caseXYZ:
statements;
break;
default:
statements;
break;
}
每一个switch语句应该包括一个默认的case，在默认的case之中的break是多余的，但是这样可以防止以后另外的case加入而引起的错误。
7.9try-catch语句
try-catch语句的形式如下所示：
try{
statements;
}catch（ExceptionClasse）{
statements;
}
8、空白处
8．1空行
空行通过分开那些有逻辑关联的编码区来提高可读性。
两空行的使用总是要遵循如下的操作环境：
在两个包含源文件的段之间
在定义的类和界面之间
一空行的使用总是要遵循如下的操作环境：
在两个程序之间
在一程序和它的起始语句中的两个局部变量之间
在一程序块或单行注释之前
在一程序中用以提高可读性的两逻辑段之间
8．2空格
空格的使用总是要遵循如下的操作环境：
一个后跟圆括号的关键词应当以空格来分隔。
例如：
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）;
9、命名规范
命名规范使得程序更易读易懂，同时它们又给出了标识符的功能信息，例如是否是常量、组件或类。
这对理解代码是极其有用的。
标识符类型
命名规则
举例
组件
一个唯一的组件名前缀总是以全小写的ASCII码表示，并且必须是最高级别的域名之一。
目前可用com,edu,gov,mil,net,org或ISO3166标准（1981）中规定的用于识别国家的英文两个字母的模式。
组件名的后继部分因其组织机构内部固有的命名方式而异。
这些规定说明某一目录名部分可以是区域名、部门名、项目名、机器名或注册名。
com.sun.eng
com.apple.quicktime.v2
edu.cmu.cs.bovik.cheese
类
类名应当是名词，在混合词中内部词第一个字母应当大写。
尽量保持类名简单易懂又具有说明性。
使用单词全拼，避免首字母缩略词和缩写词（除非缩写比全拼更广为使用，例如URL或HTML）。
classRaster;
classImageSprite;
界面
界面名应当同类名一样大写。
interface
RasterDelegate;
nterfaceStoring
程序
程序应当是动词，在混合词中起始词小写，每一个内部词第一个字母大写。
run（）;
runFast（）;
getBackground（）;
变量
除了变量，所有实例、类和类常量在混合词中的第一个字母应小写。
内部词第一个字母大写。
变量名即便是被允许也不能以下划线-字符或美元符$作起始。
变量名应当简短而有含义。
变量名的选取应当是有助于记忆性的，也就是说名字的设计应能指示程序中的临时解析器理解它的使用意图。
单个字符变量名应当避免，除非是临时的可以随时“丢弃”的变量。
对于临时变量，通用名可用i,j,k,m和n作为整数，c,d,和e作为字符。
inti;
charc;
floatmyWidth;
常量
变量名声明类常量和ANSI常量应当用全大写表示，单词之间用下划线（“_”）分隔。
（为了便于调试，ANSI常量应避免。
）
staticfinalint
MIN_WIDTH=4;
staticfinalint
MAX_WIDTH=999;
staticfinalint
GET_THE_CPU=1;
10程序设计惯例
10.1使用实例和类变量
没有非常好的理由，请不要声明任何实例或类变量，实例变量经常会在调用方法上起副作用。
适当的公用实例变量的例子是类实质上是一个数据结构，而不是行为的情况下使用的。
换句话说，如果你情愿用struct而不用class，那麽使用类的实例变量是恰当的。
10.2改进类变量和方法
避免用一个对象访问类（静态）变量或方法，用一个类名来代替。
例如：
classMethod（）;//OK
AClass.classMethod（）;//OK
anObject.classMethod（）;//AVOID!
10.3常量
数字常量不应该直接被编码，除了
升级会员 