JAVA编程规约.docx

1、JAVA编程规约Java编程规约1 引言 22 文件名 23 文件组织 24 缩进格式 55 注释 76 声明 127 语句 148 空白 179 命名规范 1910 编程惯例 2011 Log 2212 代码示例 241 引言1.1 为什么需要编码规范编码规范对编程人员来说重要性有很多理由： 一个软件的生命周期中有百分之八十的时间是在维护。 几乎没有哪个软件是完全由它的原担当来进行维护的。 编码规范可以提高代码的可读性， 可以让其他人员理解得更快， 更清晰。 在开发产品的时候， 需要保持所有产品之间的风格一致性。2 文件名2.1 文件名后缀文件类型后缀Java source.javaJava

2、 class.class3 文件组织每个文件的组成部分应该以空行和适当的注释分开。一个文件超过2000行会变得冗长， 应该尽量避免。3.1 Java 程序文件每个Java程序应该包括单个public的class或者interface。 当私有的classes与interface与一个公有的class关联的时候， 你应该将它们放在同一个文件中作为公有的class。 公有的class应该是文件的第一个class或interface。Java文件有着以下的组织顺序 文件头注释 包与导入类声明 类与接口声明3.1.1 文件头注释所有的程序文件应该以注释开始， 该注释列出类名， 版本信息， 日期， 以及

3、版权等。每个项目应该统一起来， 格式要一致。 /*/系统名称：XXXXXXXX/模块名称：XXXXXXXX/版本信息：/ 版本 日期 作者 备注/ 1.1 2008/02/20 張三 新規作成/ 1.1 2008/02/21 張三 XXXXXXXX/*3.1.2 包与导入类第一个无注释行是一个包声明， 在这之后是导入类声明， 如： package java.awt;import java.awt.peer.CanvasPeer;注：包名应该全部是小写的字母， 一般的应该以最高的域名如：com, edu, gov, mil, net, org, 或以两个字母标识的国家名字开始。 或者以项目的名字

4、开始。在导入类的时候， 注意不要用import java.awt.*; 的类似方法， 要一个一个class具体导入， 并且按照字母顺序排列， 不同package中或功能的class要以一空行隔开。 这样别人阅读程序的时候能够快速知道并定位到相关的class。 如：package cscweb.preserve.model;import java.util.ArrayList;import org.apache.log4j.Category;import mon.ejb.CSCWebException;import mon.ejb.PJCodeBook;import cscweb.util.Da

5、teUtil;import cscweb.util.MessageManager;import cscweb.preserve.data.HozenActionDefMasterData; import cscweb.preserve.ejb.PreserveDefReg;import cscweb.preserve.ejb.PreserveDefRegHome;注：若使用eclipse可通过快捷键ctrl+shift+o完成。3.1.3 类与接口声明下面这个表格描述了一个类或接口的组成成员定义， 并按规定的顺序排列， 具体实例请见（Java代码实例）类/接口组成备注1 类/接口文档注释就是一

6、些功能说明以及作者版本等等2 类或接口声明3 类/接口的执行注释(可选)这个注释应该包含所有不适合这个类或接口范围的信息 4 类静态(static)变量 首先是公有(public)类变量， 然后是保护变量(protected), 接着是package内可访问变量(无范围修饰符), 最后是私有变量(private)。 5 实例变量顺序同上 6 构造函数7 方法方法应该以功能进行组合， 而不应该以可访问范围进行分类组合。 比如： 一个私有的方法可以在两个公有的方法之间， 目的是为了使程序更易读好懂。4 缩排格式每个缩进单元应该是四个空格， 到底是用空格或TAB来进行缩排并未明确指定。但是建议用TA

7、B键来进行缩进。 文件中不要一会儿用空格一会儿用TAB键， TAB键要设成四个空格的宽度。 4.1 行宽每行避免超过80个字符， 因为有的终端和编辑工具不能很好的处理超过80字符的行。4.2 换行当一个表达语句一行不适合的时候， 应该用以下的原则进行分行： 在逗号之后 在一个操作符之前 在优先度高的地方 新行的开始应该与上一行同一级别的地方对齐。 如果满足以上的原则的新行的开始比较靠右， 应该用8个空格进行缩排。下面是两个调用方法换行例子：someMethod( longExpression1, longExpression2, longExpression3, longExpression4

8、, longExpression5);var = someMethod1(longExpression1, someMethod2(longExpression2, longExpression3); 下面是两个算术运算换行的例子。 第一个是建议使用的， 因为换行在括号的外面， 满足优先度高的原则。 longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; /推荐longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * lon

9、gname6; /禁止下面是两个方法声明缩排的例子。 第一个是常规情况。 第二种情况就是应该用8个空格进行缩排的情况。/ CONVENTIONAL INDENTATIONsomeMethod(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) ./INDENT 8 SPACES TO AVOID VERY DEEP INDENTSprivate static synchronized horkingLongMethodName(int anArg, Object anotherArg, Stri

10、ng yetAnotherArg, Object andStillAnother) .条件语句需要换行的例子：/ DONT USE THIS INDENTATIONif (condition1 & condition2) | (condition3 & condition4) | !(condition5 & condition6) / BAD WRAPS doSomethingAboutIt(); / MAKE THIS LINE EASY TO MISS / USE THIS INDENTATION INSTEADif (condition1 & condition2) | (condit

11、ion3 & condition4) | !(condition5 & condition6) doSomethingAboutIt(); / OR USE THISif (condition1 & condition2) | (condition3 & condition4) | !(condition5 & condition6) doSomethingAboutIt(); 下面是三个使用三重表达式的例子：alpha = (aLongBooleanExpression) ? beta : gamma; alpha = (aLongBooleanExpression) ? beta : ga

12、mma; alpha = (aLongBooleanExpression) ? beta : gamma; 5 注释Java程序有两种注释：代码注释(implementation comments)与文档注释(documentation comments)。 代码注释类似于C+，用/*/以及/。 文档注释为Java独有的， 用/*/， 文档注释能够用javadoc工具生成HTML形式的文档。代码注释用于一段代码的执行说明， 而文档注释用于程序的总括描述， 比如一个类， 方法或变量的功能描述， 这些描述可以通过javadoc进行浏览， 即使在没有代码的情况下。注释应该能够给予代码概要的描述， 并

13、且能够提供直接阅读代码本身所不能得到的信息。注释应仅仅包含便于阅读和理解程序的信息。 比如对于包名与文件目录应该对应起来这种就不应该需要用注释来说明。另外代码注释也不应该重复使用， 随着代码的改修， 注释也就有可能会”过期”， 因此在代码修改的同时不要忘了将注释也同时更新。注:1. 注释往往关系到代码的品质， 写注释的时候也要注意写得更清晰一点。 2. 注释也不应该用大的框框包围起来， 比如用*号或其它的字符画的框框。3. 注释不应该含有特殊的字符， 比如退格键等。5.1 代码注释格式程序代码注释有四种方式: 块(block), 单行（single-line）, （trailing）, 行尾（

14、end-of-line）。5.1.1 块注释块注释用在文件，方法，数据结构以及运算法则等方面的描述。 块注释应该在每个文件的开头以及每个方法的前面。 当然也可以用在方法的里面， 但是一定要与代码的缩排一致。块注释也应该与前面代码之间有一空行。 /* * Here is a block comment. */块注释可以以/*-开头， 当indent(1)碰到它的时间， 将不会对它重新格式化， 如：/*- * Here is a block comment with some very special * formatting that I want indent(1) to ignore. *

15、* one * two * three */ 注: 如果你不用indent(1), 你就用不着用/*-或为了防止别人在你的程序上用 indent(1) 而作出让步。5.1.2 单行注释短的说明可以用一行注释并且要与代码缩排一致对齐，如果一行注释写不下就得用前面所说的块注释方法。 (参见 5.1.1) 单行前面一般得要有一空行， 下面是一个单行注释的例子。if (condition) /* Handle the condition. */ .5.1.3 Trailing Comments很短的注释可以跟代码在同一行上，但必须跟代码有足够的距离， 如果在一块代码中有许多这样的注释， 它们必须用ta

16、b键设置来进行缩排对齐， 如下例：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-fl

17、ip./ ./else / return false;/5.2 文档注释先给个简单的例子： /* * Process an HTTP request. * * param request The servlet request we are processing * param response The servlet response we are creating * * return true if the process is successful * false if the process is failed * * exception IOException if an inpu

18、t/output error occurs * exception ServletException if a servlet exception occurs */protected boolean process(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException 可以看到方法说明， 和下面的标签（TAG）有一空行， 不同的标签之间应该空一行。 常用的标签也就是上面所看到三个， param指方法参数， return 指方法的返回值， exception指

19、方法可能会抛出的例外。更详细的说明请参照 How to Write Doc Comments for Javadoc ， 它包括文档注释的标签使用 (return, param, see): 文档注释描述Java classes, interfaces, constructors, methods, 以及 fields. 每个文档注释用/*.*/进行分割, 每个类， 接口， 或方法都有一个注释， 这种注释得在声明之前：/* * The Example class provides . */public class Example .注意的是处在最顶层的类和接口不用缩进。 文档注释的第一行(/*

20、)跟所有注释的代码对齐， 后面的*多缩进一个空格(*号对齐)。文档注释不应该用在方法或构造函数的内部， 因为Java只会关联第一个声明之前的文档注释与这个声明。5.3 维护注释在项目后期维护的时候， 特别是维护别担当程序， 必须要加上必要的注释， 一般有以下几种情况： 单行修改： / modified by username on yyyy/mm/dd for指摘票名/ rec.setDeleteFlg( CodeBook.DELETE ); / oldrec.setDeleteFlg( CodeBook.NO_DELETE );/ new 多行修改 /* commented by usern

21、ame on yyyy/mm/dd for指摘票名 doInit(); . */ / added by username on yyyy/mm/dd for 指摘票名 doNewInit(); . / end of added 如果是变更比较大的场合， 需要在版本信息一栏注上说明， 如： 参照：3.1.1 文件头注释的履历。6 声明6.1 每行声明数建议一行只有一个声明， 也便于注释。换句话说也就是int level; / indentation levelint size; / size of table比下面优先使用int level, size;更不要将不同类型的声明放在同一行， 例：

22、int foo, fooarray; / WRONG!注: 上面的这个例子在类型和变量之间用了空格， 另一个可选的方法是用tab健， 如：int level; / indentation levelint size; / size of tableObject currentEntry; / currently selected table entry6.2 初期化尽量在声明的地方进行初期化， 不过当变量需要根据后面的计算来进行赋值的时候也可不要进行初期化。6.3 声明点最好将声明摆在每一块的开始。(一块一般指是用围起来的一段代码) 不要等到变量第一次使用的时候再去初期化， 它有可能会使粗心的

23、程序员迷惑或使这段范围内的代码降低了灵活性。 void myMethod() int int1 = 0; / beginning of method block if (condition) int int2 = 0; / beginning of if block . 有一个例外就是在for循环体中可以定义索引：for (int i = 0; i maxLoops; i+) . 不要在块内部定义与外部相同名字的变量， 比如：int count;.myMethod() if (condition) int count = 0; / AVOID! . .6.4 类与接口声明当编写Java类与接口

24、的时候， 下面一些规则得要遵守： 在方法名字与后面的圆括号(之间以及圆括号与后面的参数列表之间都不应该有空格。 起始大括号 应该出现在跟声明同一行上， 且与前面有一空格。 结束大括号 应该另起一行， 并且与开始大括号相匹配对应， 不过当语句为null时例外， 应该在 立马用来结束， 例：class Sample extends Object int ivar1; int ivar2; Sample(int i, int j) ivar1 = i; ivar2 = j; int emptyMethod() . 方法之间应该用一空行分隔开7 语句7.1 简单语句每行至多一个语句， 例:argv+; / Correctarg