JAVA编程语言编码规范

JAVA编程语言的代码惯例1、 介绍1 1为什么要有代码惯例代码惯例之所以重要有以下几点原因： 软件寿命价值的80%是维护。几乎没有软件在整个使用过程中都有由原作者维护。代码惯例增加了软件包的可读性，使工程师们能更快、更完整地理解新软件。如果你想把你的原始代码变成产品，你需要确认它是否和你生产的其它产品一样有好的包装。1 2确认这个文件在SUN 公司的JAVA语言说明书中反映了JAVA语言编码标准。这方面规定主要来自Peter King,Patrick Naughton,Jonni Kanerva,and Scott Hommel.关于这个文档的改写、修改或再分配的问题，请看版权公告。对于这个文档的建议请发贴自alans2-文件名这一节列举了常用的文件后缀与名称。21文件后缀JAVA使用以下后缀：文件种类后缀JAVA source.javaJAVA bytecode.class22普通文档名称通常用的文档名称文档名称使用GNUmakefilemakefile最恰当的名字。我们使用gnumake制造我们的软件。Readme概括特定目录内容的文档的最恰当名称。3. 文件的组织结构一个文件应当由多个被分隔的段组成，并由空行和可选择注释来识别。超过2000行的文件由于冗长而应当避免。Java程序的正确格式可参看第19页的范例“Java源文件范例”。31 Java源文件每一个Java源文件包含一个单一的公共类或界面。当私有类或界面与一个公共类发生联系时，你可以将它们以一个公共类放入同一个源文件。公共类应当是文件中的第一类或界面。Java源文件有如下次序：起始注释（参看第4页“起始注释”）组件和导入语句类和界面声明（参看第4页“类和界面声明”）311 起始注释所有源文件应当以C格式注释开始，并列出类名，版本信息，时间和版权说明：/*类名*版本信息*时间*版权说明*/312 组件和导入语句对于大部分Java源文件而言，第一个无注释行是组件语句。之后，紧跟着是导入语句。举例如下：组件 java.awt;导入 java.awt.peer.CanvasPeer注释：对于唯一的组件名，第一部分总是小写的ASCII码格式的文本文件，并且是最高级别的域名之一。目前可用com,edu,gov,mil,net或ISO3166标准（1981）中规定的用于识别国家的英文两个字母的模式。313 类和界面声明下表按出现的先后顺序描述了一个类或界面说明的各部分。参见第19页“java源文件范例”中一个包含注释的示例。类/界面声明的各部分注释1类/界面文档注释(/*/)参看第9页“文挡注释”中注释的具体内容2类或界面语句3类/界面补充注释（/*/），如果必要的话这一注释应包含任一类宽或界面宽度的信息，它不适合于类/界面文档注释。4类（静态的）变量首先是公共类变量，其次是保护类，然后是组件级（无访问修改权），最后是私有类。5实例变量首先是公共类，其次是保护类，然后是组建级（无访问修改权），最后是私有类。6构成7过程这些过程应当以功能而非作用域和可访问性来分组。举例说明，一个私有类变量过程可在两个公共实例过程中。其目的是使读和理解代码更为容易。4、 缩进格式四个空格作为一个缩进单位。确切的缩进格式结构（空格符与制表符）未被规范。表格的设置必须在每8个空格后（而非4个）。41 行的长度由于难于被大多数终端和工具进行处理，应当避免一行超过80个字符。注释：在文档中所列举的范例其行的长度应稍短些，一般不超过70个字符。42 绕回行当表达式一行无法写完时，使用以下一般规则进行中断：在逗号后中断。在一个运算符前中断。优先选择高级中断指令。新行起始表达式的位置应与旧行表达式的位置对齐。如果上述规则导致代码混乱或编码时顶到了右边界，以8个空格代替。以下是几个中断程序的调用范例：someMethod(longExpression1, longExpression2, longExpression3, longExpression4, longExpression5);var = someMethod1(longExpression1, someMethod2(longExpression2, longExpression3);以下是两个关于中断算术表达式的例子。第一个例子由于中断发生在插入表达式以外，因而选择了高级中断指令。longName1 = longName2 * (longName3 + longName4 longName5) + 4 * longname6; / PREFERlongName1 = longName2 * (longName3 + longName4longName5) + 4 * longname6; / AVOID 以下是两个关于缩进程序的说明。第一个例子是常规情况。第二个例子如果采用常规缩进方式，第二和第三行在换行时必然顶至最右，取而代之应空8格。/常规的缩进方式someMethod(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) 。/缩8个空格以避免更深的锁进private static synchronized horkingLongMethodName(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) 。由于常规的4空格缩进方式使得体看上去过于复杂，对于语句的绕回行我们一般采用8空格缩进方式。举例如下：/不要使用这种缩进方式if (condition1 & condition2) (condition3 & 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 &condition6) doSomethingAboutIt();以下有三种可行的方式来格式化三元表达式：alpha = (aLongBooleanExpression) ? beta : gamma;alpha = (aLongbooleanExpression) ? beta :gamma;alpha = (aLongBooleanExpression) ? beta : gamma;5 注释JAVA 程序可以有二种类型的注释：执行注解和文件注释。执行注释是建立在C+之上的，以/*/为分隔符的注释；文件注释（即通常所说的doc comment）是一种纯JAVA 注释，以/*/为分隔符。Doc comment (文件注释)能够通过JAVADOCA工具被摘录成HEML文件。执行注释是指为代码注解释，或为特别执行注解释。Doc 注释旨在从一个自由执行的程序描述代码的规范，对于软件开发者来说，手边不再需要源代码就可以阅读。注释通常用于对代码做总的描述，同时提供附加的信息，这从代码本身来看是不容易得到的。其包含的信息只与阅读、理解该程序有关，例如：一个相应组件如何被建立的信息或驻足在何地址录下的信息都将被包含在一个注解中。对于重要的、非显而易见的设计决定的讨论是适当的，但是应该避免重复信息在代码中出现。而对于多余注释，则很容易成为过时的。总的说来，应当避免把过时的注释做为编码的进展。注意：经常出现的注释有时反映编码质量的低下。当你觉得不得不添加注释时，建议你最好重新编写，使得编码更清晰。注释不能以星号或是其它字符为标识被附在一个大的逻辑单元内。注释也不能包括特殊字符例如form-feed和backspace。5.1 执行注释的格式程序可以有四种注释风格：块、单行、跟踪和行尾。5.1.1块注释块注释用于提供文件的描述、方法、数据结构和运算法则。块注释用于每个文件的开始和方法之前。也可以用在其他地方，比如用在方法中。在一个函数或方法中的块注释，应和他们描述的代码排列到同一级别上。块注释应设置在一个空行的开始。/* * Here is a block comment. */块注释以/*开始，并且单独领导一行，缩进一格作为块注释的开始，这已经是约定俗成的，不需要另外重新定义格式。例如：/*- * 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 someone 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); /* 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 Example class provides . */public class Example .注意顶级类和界面不缩进，子类和界面则要缩进。类和界面的第一行文件注释不缩进，后面的注释行有有一个空格的缩进。子类，包括容器，有4个空格和五个空格的缩进。如果你需要给出关于类、界面, 变量, 或方法的信息，这些信息以文件的方式给出是不适当的，那麽你可以直接的在声明之后使用执行块注释或单行注释。例如，类执行的细节信息应放进执行块注释中，并跟在类语句之后，而不是放在类的文件注释中。文件注释不应该放到方法或容器的定义块中，因为Java将文件注释和第一个注释之后的声明发生联系。6、声明6.1每一行的数量每一行中都应有相应的注释，换句话说int level; / indentation levelint size; / size of table这种形式是首选的，而不是int level, size;不要将不同类型的放入同一行中，例如：int foo, fooarray; /WRONG!注意：上面的例子中在类型和标识之间有一个空格，另一个可接受的方法是用tab，例如：intlevel; / indentation levelintsize; / size of tableObjectcurrentEntry; / currently selected table entry6.2 初始化被声明的局部变量，应设法将其初始化。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 = 0) ? x : -x;10.5.4特殊注释用XXX作为注释信息来试图标记一些事情，那是不切实际的。用FIXME标记某些事情，那也是不切实际的。11代码例子11.1 JAVA源文件例子下面的例子显示了如何格式化一个包含单一公用类的JAVA源文件。同样的界面也被格式化，更多的信息请参见Class and Interface Declarations on page 4 and Documentation Comments on page 9/* * (#)Blah.java 1.82 99/03/18 * * Copyright (c) 1994-1999 Sun Microsystems, Inc. * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. * All rights reserved. * * This software is the confidential and proprietary information of Sun * Microsystems, Inc. (Confidential Information). You shall not * disclose such Confidential Information and shall use it only in * accordance with the terms of the license agreement you entered into * with Sun. */package java.blah;import java.blah.blahdy.BlahBlah;/* * Class description goes here. * * version 1.82 18 Mar 1999 * author Firstname Lastname */public class Blah extends SomeClass /* A class implementation comment can go here. */ /* classVar1 documentation comment */ public static int classVar1; /* * classVar2 documentation comment that happens to be * more than one line long */ private static Object classVar2; /* instanceVar1 documentation comment */ public Object instanceVar1; /* instanceVar2 documentation comment */ protected int instanceVar2; /* instanceVar3 documentation comment */ private Object instanceVar3; /* * .constructor Blah documentation comment. */ public Blah() / .implementation goes here. /* * .method doSomething documentation comment. */ public void doSomething() / .implementation goes here. /* * .method doSomethingElse documentation comment. * param someParam description */ public void doSomethingElse(Object someParam) / .implementation goes here.