[1.0]Java代码基本规范

Java编码基本规范注：本文档只关注java的基本规范，至于项目中的组织结构等的规范请参阅dev_guid.doc0.开始为什么要有编码规范编码规范对于程序员而言尤为重要，有以下几个原因：◆一个软件的生命周期中，80%的花费在于维护。◆几乎没有任何一个软件，在其整个生命同期中，均由最初的开发人员来维护。◆编码规范可以改善软件的可读性，可以让程序员尽快而彻底地理解新代码。◆如果你将源码作为产品发布，就需要确认它是否被很好的打包并且清晰无误，一如你已构建的其它任何产品。为了执行规范，每个软件开发人员必须一致遵守编码规范。每个人!!!1.文件名这部分列出了常用的文件名及其后缀。1.1.文件后缀(FileSuffixes)Java程序使用下列文件后缀：文件类别文件后缀Java源文件.javaJava字节码文件.class1.2.常用文件名(CommonFileNames)常用的文件名包括：文件名用途GNUmakefilemakefiles的首选文件名。我们采用gnumake来创建(build)软件。README概述特定目录下所含内容的文件的首选文件名。2.文件组织(FileOrgnization)一个文件由被空行分割而成的段落以及标识每个段落的可选注释共同组成。超过2000行的程序难以阅读，应该尽量避免。“Java源文件范例”提供了一个页面布局合理的Java程序范例。2.1.Java源文件(JavaSourceFiles)◆每个Java源文件都包含一个单一的公共类或接口。◆若私有类和接口与一个公共类相关联。可以将它们和公共类放入同个源文件。公共类必须是这个文件中的第一个类和接口。Java源文件还遵循以下规则：◆开头注释(参见“开头注释”)◆包和引入语句(参见“包和引入语句)◆类和接口声明(参见“类和接口声明)2.1.1.开头注释(BEGINNINGCOMMENTS)所有的源文件都应该在开头有一个C语言风格的注释，其中列出数出类名、版本信息，日期和版权声明：/***Function:TODO*FileName.java*FileCreatedon2011-3-30*@Version1.0**Copyright2009baidu.com*Allrightsreserved.*/2.1.2.包和引入(PACKAGEANDIMPORTSTATEMENTS)在多数Java源文件中，第一个非注释行是包语句行。在它之后可以跟引入语句。例如：packagejava.awt;importjava.awt.peer.CanvasPeer;2.1.3.类和接口声明(CLASSANDINTERFACEDECLARATIONS)下表描述了类和接口声明的免修部分以及它们出现的先后次序。类/接口声明的各部分注解1类/接口文档注释(/**…*/)该注释中所包含的信息，参见“文档注释”2类/接口的声明3类/接口实现的注释(/*…*/)如果有必要的话该注释应包含任何有关整个类或接口的信息，而这些信息又适合作为类/接口文档注释。4类的(静态)变量首先是类的public变量，随后是protected变量，再后是包一级别的变量(没有访问修饰符)，最后是private变量。5实例变量首先是public变量，随后是protected变量，再后是包一级别的变量(没有访问修饰符)，最后是private变量。6构造器7方法这些方法应该按功能，而非作用域或访问权限，分组。3.缩进排版(Indentation)4个空格常被作为缩进排版的一个单位。严禁使用“tab”缩进（eclipse中可以将tab键自动转换为空格）。3.1.行长度尽量避免一行长度超过80个字符，因为很多终端和工具不能很好处理之。注意：用于文档是的例子应该使用更短的行长，长度一般不超过70个字符。3.2.换行(WrappingLines)当一个表达式无法容纳在一行内时，可以依据如下一般规则断开之：◆在一个逗号后面断开。◆在一个操作符前面断开。◆宁可选择较高级别的(higher-level)的断开，而非较低级别(lower-level)的断开。◆新的一行应该与上一行同一级别表达式的开头处对齐。◆如果以上规则导致你的代码混乱或者使你的代码都堆挤在右边，那就代之以缩进8个空格。以下是断开方法的一些例子：someMethod(longExpression1,longExpression2,longExpression3,longExpression4,longExpression5);var=someMethod1(Expression1,someMethod2(longExpression2,longExpression3));以下是两个断开算术表达式的例子。前者更好，因为断开处位于括号表达式的外边，这是个较高级别的断开。longName1=longName2*(longName3+longName4-longNeme5)+4*longName6);//PREFFERlongName1=longName2*(longName3+longName4-longName5)+4*longName6;//AVOID以下是两个缩进方法声明的例子。前者是常规情形，后者若使用常规的缩进方式将会使第二行和第三行移得很靠右，所以代这以缩进8个空格。//CONVENTIONINDENTATIONsomeMethod(intanArg,ObjectanotherArg,StringyetAnotherArg,ObjectandStillAnother){……}//INDENT8SPACESTOAVOIDVERYDEEPINDENTSprivatestaticsynchronizedhorkingLongMethodName(intanArg,ObjectanotherArg,StringyetAnotherArg,ObjectandStillAnother){……}if语句的换行通常使用8个空格的规则，因为常规缩进(4个空格)会使语句看起来比较费劲。比如：//DON’TUSETHISINDENTATIONif((condition1&&condition2)||(condition3&&condition4)||!(condition5&&condition6)){//BADWRAPSdoSomethingAboutIt();//MAKETHISLINGEASYTOMISS}//USETHISINDENTATIONINSTEADif((condition1&&condition2)||(condition3&&condition4)||!(condition5&&condition6)){doSomethingAboutIt();}//ORUSETHISif((condition1&&condition2)||(condition3&&condition4)||!(condition5&&condition6)){doSomthingAoutIt();}这里有三种可行的方法用于处理三元运算表达式：alpha=(aLongBooleanExpression)?beta:gamma;alpha=(aLongBooleanExpression)?beta:gamma;alpha=(aLongBooleanExpression)?beta:gamma;4.注释(Comments)Java程序有两类注释：实现注释(implementationcomments)和文档注释(documentcomments)。实现注释是那些在C++中见过的，使用/*…*/和//界定的注释。文档注释(被称为“doccomments”)是Java独有的，并由/**…*/界定。文档注释可以通过javadoc工具转换成HTML文件。实现注释用以注释代码或或者实现细节。文档注释从实现自由(implemtentation-free)的角度描述代码的规范。它可以被那些手头没有源码的开发人员读懂。注释应被用来给出代码的总括，并提供代码自身没有提供的附加信息。注释应该仅包含与阅读和理解程序有关的信息。例如，相应的包如何被建立或位于哪个目录下之类的信息不应包括在注释中。在注释里，对设计决策中重要的或者不是显而易见的地方进行说明是可以的，但应避免提供代码中已清晰表达出来的重复信息，多余的注释很容易过时。通常应避免那些代码更新就可能过时的注释。注意：频繁的注释有时反映出代码的低质量。当你觉得被迫要加注释的时候，考虑一下重写代码使其更清晰。注释不应写在用星号或字符画出来的大框里。注释不应包括诸如制表符和回退符之类的特殊字符。4.1.实现注释的格式(ImplementationCommentFormats)程序可以有4种实现注释的风格：块(Block)，单行(single-line)，尾端(trailing)和行末(end-of-line)。4.1.1.块注释块注释通常用于提供对文件，方法，数据结构和算法的描述。块注释被置于每个文件的开始处以及每个方法之前。它们也可以被用于其他地方，比如方法的内部。在功能和方法内部的块注释应该和它们所描述的代码具有一样的缩进格式。块注释之首应该有一个空行，用于把块注释和代码分割开来，比如：/**Hereisablockcomment.*/块注释可以以/*-开头，这样indent(1)就可以将之识别为一个代码块的开始，而不会重排它。/*-*Hereisablockcommentwithsomeveryspecial*formattingthatIwantindent(1)toignore.**one*two*three*/注意：如果你不使用indent(1)，就不必在代码中使用/*-，或为他人可能对你的代码运行indent(1)让步。参见“文档注释”。4.1.2.单行注释(SINGLE-LINECOMMENTS)短注释可以显示一行内，并与其后的代码具有一样的缩进层级。如果一个注释不能在一行内写完，就该块注释(参见“块注释”)。单行注释之前应该有一个空行。以下是一个Java代码中单行注释的例子：if(condition){/*Handlethecondition.*/……}4.1.3.尾端注释(TRAILINGCOMMENTS)极短的注释可以与它们所要描述的代码位于同一行，但是应该有足够的空白来分开代码和注释。若有多个短注释出现于大段代码中，它们应该具有相同的缩进。以下是一个Java代码中尾端注释的例子：if(a==2){returnTRUE;/*specialcase*/}else{returnisPrime(a);/*worksonlyforodda*/}4.1.4.行末注释(END-OF-LINECOMMENTS)注释界定符“//”，可以注释掉整行或者一行中的一部分。它一般不用于连续多行的注释文本；然而，它可以用来注释掉多行的代码段。以下是所有三种风格的例子：if(foo1){//Doadouble-filp.……}else{returnfalse;}//if(bar1){//////Doatriple-filp.//……//}//else{//returnfalse;//}4.1.5.文档注释(DOCUMENTATIONCOMMENTS)注意：此处描述的注释格式之范例，参见“Java源文件范例”若想了解更多，参见“HowtoWriteDocCommentsforJavadoc”，其中包含了有关文档注释标记的信息(@return，@param，@see)：若想了解有关文档注释和javadoc的详细资料，参见javadoc的主页：文档注释描述Java的类、接口、构造器、方法，以及字段(field)。每个文档注释都会被置于注释界定符/**…*/之中，一个注释对应一个类、