代码和注释规范.docx
《代码和注释规范.docx》由会员分享，可在线阅读，更多相关《代码和注释规范.docx（9页珍藏版）》请在冰点文库上搜索。
代码和注释规范
文档编号
版本
1.0
JAVA编程规范
代码规范
注释规范
1．引言
本文档对Java代码的编程方法.作风做了同一规范,目标是削减编程人员代码编写中的语法错误,并经由过程加强代码的通读性和易懂性,使得代码修正和程序保护相对简略.
本文档可用作公司新进人员的培训材料,也可用作检讨代码编写质量的参考.
2．代码规范
2.1缩进
缩进必须用Tab键.不许可应用空格键缩进.每Tab缩进4个空格长度.
2.2页宽
页宽设置为80字符,即每行代码不应超过80字符数.
注：
写在文档中的例子每行的宽度应更短,一般不超过70字符.
2.3折行
当一个表达式或一行语句超长时（超出页宽）,必须按以下规矩进行折行：
●在逗号之后折行
●在操作符之前折行
●当表达式或语句有多层嵌套时,尽量避免或削减拆开嵌套层次
●折行代码的缩进地位应对齐于前一行的同一嵌套层次
●若沿用以上规矩导致代码混乱或者代码太靠右,就用2个Tab缩进代替
这里是一些办法界说和挪用的折行例子：
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;//准确的
longName1=longName2*（longName3+longName4
-longName5）+4*longname6;//避免的
下面是两个办法界说的缩进例子.第一个是规范的例子.第二个例子,假如沿用常规的缩进规范,第二行和第三行将会紧靠右端,左边留白太多,是以用以2个Tab字符替代缩进.
//规范的缩进
someMethod（intanArg,ObjectanotherArg,StringyetAnotherArg,
ObjectandStillAnother）{
...
}
//用2个Tab字符来避免缩进过深
privatestaticsynchronizedhorkingLongMethodName（intanArg,
ObjectanotherArg,StringyetAnotherArg,
ObjectandStillAnother）{
...
}
对于if语句的折行必须用2个Tab缩进.常规的缩进可能导致别扭的代码构造,例如：
//不应用这种缩进
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.4打印语句
程序调试时,打印语句（System.out.println（））必须靠齐代码页左端书写,便于整顿代码时去除此调试信息.
3．注释规范
Java程序有两种注释方法：
代码注释和文档注释.代码注释相似于C++中的注释,包含在/*…*/之中或者在//之后.文档注释是Java所特有的doc注释,它以/**开端,到*/停止.文档注释主如果为支撑JDK对象javadoc而采用的.Javadoc能辨认注释顶用标记@标识的一些特别变量,并把doc注释参加它所生成的HTML文件.
代码注释可以用来注释失落（屏障）代码,也可用来对某一履行语句而作具体的解释.文档注释是指对代码规格的描写,这些与履行无关的解释用来给那些不须要懂得和处理源代码的开辟者应用.
注释不能放在用星号或其它符号画出来的大方框内.
注释中不能包含特别字符,例如制表符和回格符.
3.1代码注释
程序中可以有四种代码注释格局：
块注释.单行注释.行尾注释和停止行注释.
3.1.1块注释
多行文本注释,被用来供给文件.办法.数据构造和算法的具体描写信息.可用在每个文件的开首和每个办法之前.也可以用在其它地方,例如办法体内.
当块注释在函数或办法体内应用时,它们必须和其描写的代码在同一级缩进上.
块注释前必须有一空行以和其它的代码分离隔.
/*
*Hereisablockcomment
*/
3.1.2单行注释
短的注释可以放在一行,和追随的代码有雷同的缩进.
假如一个注释不能在一行内写完,则必须应用块注释格局（参考5.1.1节）.
一个单行注释前必须有一空行和其它代码离开.
这里是一个Java代码的行注释例子：
if（condition）{
/*Handlethecondition.*/
…
}
3.1.3行尾注释
异常短的注释可以和其描写的代码写在同一行,但必须和代码分隔的足够开.假如一个代码块中有超过一个以上的行尾注释,它们必须用雷同的缩进对齐.例如：
if（a==2）{
returnTRUE;/*specialcase*/
}else{
returnisPrime（a）;/*worksonlyforodda*/
}
3.1.4停止行注释
注释从//开端,终止于行尾,可以单独一行也可以作为其它行的一部分.不能用做多行文本注释.例：
if（foo>1）{
//Doadouble-flip.
…
}else{
returnfalse;//Explainwhyhere.
}
每个函数体.办法体.轮回体和if语句代码过长或者嵌套过深时,必须在停止符后加上//注释.例如：
publicvoiddoSomething（）{
…
while（condition）{
…
}//endwhile
…
}//enddoSomething
3.1.5注释代码
程序中非物理删除代码时,须要注释失落代码.有三种方法：
1．需注释代码行数较少时,应用//.例如：
//if（bar>1）{
//
////Doatriple-flip.
//…
//}else{
//returnfalse;
//}
2．需注释代码行数较多时,应用if（false）.请求if（false）必须靠齐代码页的左端.例如：
if（false）{
…
}
3．块注释.应用块注释独一要留意的是,当被注释的程序段已嵌套有块注释和单行注释时,会产生注释凌乱,导致某些语句行离开注释.
3.2文档注释
文档注释描写Jvav类.接口.构造.办法和域.每个文档注释被包含在注释符/**…*/中,一个类（接口.成员）一个注释.文档注释必须在声明之前：
/**
*TheExampleclassprovides…
*/
办法注释必须是以下情势：
/**
*【办法的处理内容】
*@param【参数名】,【参数解释】
*@return【返回值解释】
*@exception【破例】
*/
1办法的处理内容
写入办法的处理概要.
2参数名,参数説明
写入参数变量名和内容.
（有复数个时,对复数行描写.复数描写@param）
（无参数的情形时可省略）
3返回值解释
写入返回值的内容.
（有复数个时,对复数行描写.复数描写@return）
（没有返回值时可省略）
4破例
办法描写throw破例的名称.
（有复数个时,对复数行描写.复数描写@exception）
（没有throw破例的场合可省略）
文档注释不许可写在办法体或构造界说体之内.Java文档会主动将注释之后的语句声明和注释联系关系在一路.
关于Java文档注释的具体规范,请参考以下文档：
附录A文档更新记载
日期
修正人员
描写
2002-9-2
严厉生
创建草稿,版本1.0
升级会员 