JAVA编码规约.docx

1、JAVA编码规约JAVA编码规约1、 介绍1 1为什么要有代码惯例代码惯例之所以重要有以下几点原因： 软件寿命价值的80%是维护。几乎没有软件在整个使用过程中都有由原作者维护。代码惯例增加了软件包的可读性，使工程师们能更快、更完整地理解新软件。如果你想把你的原始代码变成产品，你需要确认它是否和你生产的其它产品一样有好的包装。1 2确认这个文件在SUN 公司的JAVA语言说明书中反映了JAVA语言编码标准。这方面规定主要来自Peter King,Patrick Naughton,Jonni Kanerva,and Scott Hommel.关于这个文档的改写、修改或再分配的问题，请看版权公告。对

2、于这个文档的建议请发贴自alans2-文件名这一节列举了常用的文件后缀与名称。21文件后缀JAVA使用以下后缀：文件种类后缀JAVA source.javaJAVA bytecode.class22普通文档名称通常用的文档名称文档名称使用GNUmakefilemakefile最恰当的名字。我们使用gnumake制造我们的软件。Readme概括特定目录内容的文档的最恰当名称。3. 文件的组织结构一个文件应当由多个被分隔的段组成，并由空行和可选择注释来识别。超过2000行的文件由于冗长而应当避免。Java程序的正确格式可参看第19页的范例“Java源文件范例”。31 Java源文件每一个Java源

3、文件包含一个单一的公共类或界面。当私有类或界面与一个公共类发生联系时，你可以将它们以一个公共类放入同一个源文件。公共类应当是文件中的第一类或界面。Java源文件有如下次序： 起始注释（参看第4页“起始注释”） 组件和导入语句 类和界面声明（参看第4页“类和界面声明”）311 起始注释所有源文件应当以C格式注释开始，并列出类名，版本信息，时间和版权说明：/*类名*版本信息*时间*版权说明*/312 组件和导入语句对于大部分Java源文件而言，第一个无注释行是组件语句。之后，紧跟着是导入语句。举例如下：组件 java.awt;导入 java.awt.peer.CanvasPeer注释：对于唯一的组

4、件名，第一部分总是小写的ASCII码格式的文本文件，并且是最高级别的域名之一。目前可用com,edu,gov,mil,net或ISO3166标准（1981）中规定的用于识别国家的英文两个字母的模式。313 类和界面声明下表按出现的先后顺序描述了一个类或界面说明的各部分。参见第19页“java源文件范例”中一个包含注释的示例。类/界面声明的各部分注释1类/界面文档注释(/*/)参看第9页“文挡注释”中注释的具体内容2类或界面语句3类/界面补充注释（/*/），如果必要的话这一注释应包含任一类宽或界面宽度的信息，它不适合于类/界面文档注释。4类（静态的）变量首先是公共类变量，其次是保护类，然后是组件

5、级（无访问修改权），最后是私有类。5实例变量首先是公共类，其次是保护类，然后是组建级（无访问修改权），最后是私有类。6构成7过程这些过程应当以功能而非作用域和可访问性来分组。举例说明，一个私有类变量过程可在两个公共实例过程中。其目的是使读和理解代码更为容易。4、 缩进格式四个空格作为一个缩进单位。确切的缩进格式结构（空格符与制表符）未被规范。表格的设置必须在每8个空格后（而非4个）。41 行的长度由于难于被大多数终端和工具进行处理，应当避免一行超过80个字符。注释：在文档中所列举的范例其行的长度应稍短些，一般不超过70个字符。42 绕回行当表达式一行无法写完时，使用以下一般规则进行中断： 在逗

6、号后中断。 在一个运算符前中断。 优先选择高级中断指令。 新行起始表达式的位置应与旧行表达式的位置对齐。 如果上述规则导致代码混乱或编码时顶到了右边界，以8个空格代替。以下是几个中断程序的调用范例：someMethod(longExpression1, longExpression2, longExpression3, longExpression4, longExpression5);var = someMethod1(longExpression1, someMethod2(longExpression2, longExpression3);以下是两个关于中断算术表达式的例子。第一个例子由

7、于中断发生在插入表达式以外，因而选择了高级中断指令。longName1 = longName2 * (longName3 + longName4 longName5) + 4 * longname6; / PREFERlongName1 = longName2 * (longName3 + longName4longName5) + 4 * longname6; / AVOID 以下是两个关于缩进程序的说明。第一个例子是常规情况。第二个例子如果采用常规缩进方式，第二和第三行在换行时必然顶至最右，取而代之应空8格。/常规的缩进方式someMethod(int anArg, Object anot

8、herArg, String yetAnotherArg, Object andStillAnother) 。 /缩8个空格以避免更深的锁进private static synchronized horkingLongMethodName(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) 。 由于常规的4空格缩进方式使得体看上去过于复杂，对于语句的绕回行我们一般采用8空格缩进方式。举例如下：/不要使用这种缩进方式if (condition1 & condition2) (condition3

9、& condition4) !(condition5 & condition6) /BAD WRAPS doSomethingAboutIt(); /MAKE THIS LINE EASY TO MISS /取而带之使用这种缩进方式if (condition1 & condition2) (condition3 & condition4) !(condition5 &condition6) doSomethingAboutIt(); /或使用这种方式if (condition1 & condition2) (condition3 & condition4) !(condition5 &cond

10、ition6) doSomethingAboutIt(); 以下有三种可行的方式来格式化三元表达式：alpha = (aLongBooleanExpression) ? beta : gamma;alpha = (aLongbooleanExpression) ? beta :gamma;alpha = (aLongBooleanExpression) ? beta : gamma;5 注释JAVA 程序可以有二种类型的注释：执行注解和文件注释。执行注释是建立在C+之上的，以/*/为分隔符的注释；文件注释（即通常所说的doc comment）是一种纯JAVA 注释，以/*/为分隔符。Doc c

11、omment (文件注释)能够通过JAVADOCA工具被摘录成HEML文件。执行注释是指为代码注解释，或为特别执行注解释。Doc 注释旨在从一个自由执行的程序描述代码的规范，对于软件开发者来说，手边不再需要源代码就可以阅读。注释通常用于对代码做总的描述，同时提供附加的信息，这从代码本身来看是不容易得到的。其包含的信息只与阅读、理解该程序有关，例如：一个相应组件如何被建立的信息或驻足在何地址录下的信息都将被包含在一个注解中。对于重要的、非显而易见的设计决定的讨论是适当的，但是应该避免重复信息在代码中出现。而对于多余注释，则很容易成为过时的。总的说来，应当避免把过时的注释做为编码的进展。注意：经常

12、出现的注释有时反映编码质量的低下。当你觉得不得不添加注释时，建议你最好重新编写，使得编码更清晰。注释不能以星号或是其它字符为标识被附在一个大的逻辑单元内。注释也不能包括特殊字符例如form-feed和backspace。5.1 执行注释的格式程序可以有四种注释风格：块、单行、跟踪和行尾。5.1.1块注释块注释用于提供文件的描述、方法、数据结构和运算法则。块注释用于每个文件的开始和方法之前。也可以用在其他地方，比如用在方法中。在一个函数或方法中的块注释，应和他们描述的代码排列到同一级别上。块注释应设置在一个空行的开始。/* * Here is a block comment. */块注释以/*开

13、始，并且单独领导一行，缩进一格作为块注释的开始，这已经是约定俗成的，不需要另外重新定义格式。例如：/*- * Here is a block comment with some very special * formatting that I want indent(1) to ignore. * * one * two * three */Note: If you dont use indent(1), you dont have to use /*- in your code or make any other concessions to the possibility that som

14、eone else might run indent(1) on your code.5.1.2 单行注释简短的注释可以出现在单行上，和其描述的代码在同一级别上。单行注释应遵循块注释的格式。单行注释应单起一行。例如：if (condition) /* Handle the condition. */ .5.1.3 跟踪注释简短的注释可以和其所描述的代码放到同一行上。但应和代码保持足够远的空间。如果不只一个简短的注释出现在大块的代码段中，它们应有同样的tab设置。例如：if (a = 2) return TRUE; /* special case */ else return isPrime(a

15、); /* works only for odd a */5.1.4 行尾注释/注释界定符能注释一整行或行的一部分，它不应该用在连续的多行文本注释中。然而，它可以用在连续的多行代码段中。例如：if (foo 1) / Do a double-flip. .else return false; / Explain why here./if (bar 1) / / Do a triple-flip./ ./else / return false;/5.2 文件注释文件注释描述Java类、界面、容器、方法和域，每一个文件注释都放在注释界定符/*.*/之间。注释应在声明之前。/* * The Exam

16、ple class provides . */public class Example .注意顶级类和界面不缩进，子类和界面则要缩进。类和界面的第一行文件注释不缩进，后面的注释行有有一个空格的缩进。子类，包括容器，有4个空格和五个空格的缩进。如果你需要给出关于类、界面, 变量, 或方法的信息，这些信息以文件的方式给出是不适当的，那麽你可以直接的在声明之后使用执行块注释或单行注释。例如，类执行的细节信息应放进执行块注释中，并跟在类语句之后，而不是放在类的文件注释中。文件注释不应该放到方法或容器的定义块中，因为Java将文件注释和第一个注释之后的声明发生联系。6、声明6.1每一行的数量每一行中都应

17、有相应的注释，换句话说int level; / indentation levelint size; / size of table这种形式是首选的，而不是int level, size;不要将不同类型的放入同一行中，例如：int foo, fooarray; /WRONG!注意：上面的例子中在类型和标识之间有一个空格，另一个可接受的方法是用tab，例如：int level; / indentation levelint size; / size of tableObject currentEntry; / currently selected table entry6.2 初始化被声明的局部

18、变量，应设法将其初始化。6.3 布置声明应放在块的开始。不要一直到用到第一个变量的时候才开始声明，那将使粗心的程序员迷惑，并且妨碍代码的轻便性。void myMethod() int int1 = 0; / beginning of method block if (condition) int int2 = 0; / beginning of if block . 在Java中，for循环中的指针可以在for语句中声明，例如for (int i = 0; i maxLoops; i+) . 避免在更高层的声明当中隐含局部声明，例如，不要在一个内部块中声明有相同名字的变量。int count;

19、.myMethod() if (condition) int count = 0; / AVOID! . .6.4 声明类和界面当在译码java的类和界面的时候，应遵循以下的格式化规则：列出参数时，在方法名和圆括号之间不应该有空格。出现在声明语句同一行的结尾。单起一行，但要和最近的“”匹配。但如果是空语句则例外。class Sample extends Object int ivar1; int ivar2; Sample(int i, int j) ivar1 = i; ivar2 = j; int emptyMethod() .Methods7、语句71 简单语句每行最多只能包括一个语句。

20、比如：argv+;/ Correctargc-;/Correctargv+;/argc-; /AVOID72复合语句复合语句是包括一系列包含在括号statement中的语句。请看以下例子：被包含的语句必须比复合语句缩进一格。开始的括号必须在开始复合语句的那一行的末尾；关闭的括号应该重起一行并相对复合语句的开头来说缩进。当括号是控制结构的一部分时，它们在所有语句中使用，像if-elsea或for 语句即便是简要语句。这使得增加语句非常容易，您也不必为了忘记加括号而付出艰辛的劳动。7.3 return语句在某种程度上，如果一个return语句的返回值并不非常明显，那么不应该加圆括号。例如：retu

21、rn;return myDisk.size();return (size ? size : defaultSize);7.4 if, if-else, if else-if else 语句if-else语句可以分为以下几类：if (condition) statements;if (condition) statements; else statements;if (condition) statements; else if (condition) statements; else statements;Note: if statements always use braces . Avoi

22、d the following error-prone form: if (condition) /AVOID! THIS OMITS THE BRACES ! statement;7.5 for 语句 For 语句的形式如下所示：for (initialization; condition; update) statements;一条空的for语句的形式如下所示：for (initialization; condition; update);当在初始化或更新子句的时，避免使用超过三个以上的变量，如果有必要的话，可以在for循环开始之前或结束后使用个别的语句。7.6 while 语句while

23、 语句的形式如下所示：while (condition) statements;一个空的while 语句的形式如下：while (condition);7.7 do-while 语句do-while 语句的形式如下：do statements; while (condition);7.8 switch 语句switch (condition) case ABC: statements; /* falls through */case DEF: statements; break;case XYZ: statements; break;default: statements; break;每一个

24、switch 语句应该包括一个默认的case，在默认的case之中的break是多余的，但是这样可以防止以后另外的case加入而引起的错误。7.9 try-catch 语句try-catch 语句的形式如下所示：try statements; catch (ExceptionClass e) statements;8、空白处 81 空行空行通过分开那些有逻辑关联的编码区来提高可读性。两空行的使用总是要遵循如下的操作环境： 在两个包含源文件的段之间 在定义的类和界面之间一空行的使用总是要遵循如下的操作环境： 在两个程序之间 在一程序和它的起始语句中的两个局部变量之间 在一程序块或单行注释之前 在

25、一程序中用以提高可读性的两逻辑段之间82 空格空格的使用总是要遵循如下的操作环境： 一个后跟圆括号的关键词应当以空格来分隔。例如： while (true) 。 应注意空格不能使用在一程序名和它的开放式圆括号之间。这有助于将关键词从程序指令中识别出来。 一空格应当出现在参数表中逗号之后。 所有二进制运算符（除了。），都应当从它们的操作数中以空格来分隔。空格不能将一元运算符从它们的操作数中分隔开，例如一元减、增量和减量。举例如下：a += c + d;a = (a + b) / (c *d);while (d+ = s+) n+; printSize(“size is “ + foo + “n”

26、); 在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标准（

27、1981）中规定的用于识别国家的英文两个字母的模式。组件名的后继部分因其组织机构内部固有的命名方式而异。这些规定说明某一目录名部分可以是区域名、部门名、项目名、机器名或注册名。com.sun.engcom.apple.quicktime.v2edu.cmu.cs.bovik.cheese类类名应当是名词，在混合词中内部词第一个字母应当大写。尽量保持类名简单易懂又具有说明性。使用单词全拼，避免首字母缩略词和缩写词（除非缩写比全拼更广为使用，例如URL或HTML）。class Raster;class ImageSprite;界面界面名应当同类名一样大写。interfaceRasterDelega

28、te;nterface Storing程序程序应当是动词，在混合词中起始词小写，每一个内部词第一个字母大写。run();runFast();getBackground();变量除了变量，所有实例、类和类常量在混合词中的第一个字母应小写。内部词第一个字母大写。变量名即便是被允许也不能以下划线-字符或美元符$作起始。变量名应当简短而有含义。变量名的选取应当是有助于记忆性的，也就是说名字的设计应能指示程序中的临时解析器理解它的使用意图。单个字符变量名应当避免，除非是临时的可以随时“丢弃”的变量。对于临时变量，通用名可用i,j,k,m和n作为整数，c,d,和e作为字符。int i;char c;flo

29、at myWidth;常量变量名声明类常量和ANSI常量应当用全大写表示，单词之间用下划线（“_”）分隔。（为了便于调试，ANSI常量应避免。）static final intMIN_WIDTH = 4;static final intMAX_WIDTH = 999;static final intGET_THE_CPU = 1;10 程序设计惯例10.1使用实例和类变量没有非常好的理由，请不要声明任何实例或类变量，实例变量经常会在调用方法上起副作用。适当的公用实例变量的例子是类实质上是一个数据结构，而不是行为的情况下使用的。换句话说，如果你情愿用struct而不用class，那麽使用类的实例变量是恰当的。10.2改进类变量和方法避免用一个对象访问类（静态）变量或方法，用一个类名来代替。例如：classMethod(); /OKAClass.classMethod(); /OKanObject.classMethod(); /AVOID!10.3常量数字常量不应该直接被编码，除了