Java代码编程规范1.doc

《Java代码编程规范1.doc》由会员分享，可在线阅读，更多相关《Java代码编程规范1.doc（37页珍藏版）》请在淘文阁 - 分享文档赚钱的网站上搜索。

1、 技 术 文 件 文件名称： JAVA代码编程规范 文件编号： 版 本: V2.0 文件等级：共 37 页(包括封面) 项目名称: 项目代码: 拟 制： 郭军，曹阳 单 位： 网络资源开发部 日 期： 2002年8月22日 深圳市中兴通讯股份有限公司目 录1概述41.1编程规范的必要性41.2规范文档的一些要求41.3如何使代码简洁42源文件的组织52.1Java源文件52.1.1文档开头的注释52.1.2Package和Import声明52.1.3类和接口声明53文档的缩进规则53.1行的长度53.2代码行的分割54代码的注释规则84.1代码注释的基本原则84.2注释的运用84.3Imple

2、mentation注释的格式94.3.1块注释94.3.2单行注释94.3.3后注释(trailing)104.3.4行尾注释(End-of-line)104.4文档型注释(Documentation)104.4.1位置114.4.2javadoc标签的使用124.4.3加入样例代码124.4.4生成javadoc文档135变量的声明145.1每行变量声明个数145.2变量初始化145.3变量声明的位置145.4类和接口的声明156语句166.1简单语句166.2复合语句166.3返回语句166.4if，if-else，if else-if else语句166.5for语句176.6while

3、 循环语句176.7do-while 语句176.8switch语句176.9try-catch 语句187空行和空格的使用187.1空行的使用187.2空格的使用198命名规范198.1命名的基本原则208.2成员函数的命名规则208.2.1成员访问函数的命名208.3属性域（fields/property）的命名218.3.1组件的命名218.4常量的命名228.5数组的命名228.6局部变量的命名标准228.6.1流（Streams）的命名228.6.2循环变量的命名228.6.3异常（Exception）处理中的命名238.6.4通用对象命名约定238.7类、接口、包的命名239编程规

4、范239.1访问类变量和实例239.2类变量和方法239.3常量259.4变量的声明259.5几个注意点259.5.1括号259.5.2返回值269.5.3条件运算中的表达式2610编码实例2610.1JAVA源文件的例子2611总结和索引2911.1JAVA命名规范2911.2JAVA文档注释规范2911.2.1基本原则2911.2.2注释的内容3111.3JAVA编码规范3212警惕内存泄漏3313J2EE命名规范3413.1EJB包结构3413.2Servlet包结构3613.3通用工具包结构3613.4JNDI名称3714参考书目3715细节371 概述1.1 编程规范的必要性代码编程

5、规范之所以重要是因为：l 软件生命周期中的80%时间是软件维护期；l 几乎没有任何软件在其整个生命周期中一直由它的原作者来负责维护；l 代码编程规范能够增加软件的可读性，使得软件工程师更快更准确地理解新代码l 编程规范能提高软件的封装性；1.2 规范文档的一些要求 后面文中将深入讨论结构良好的程序文档的规则和要求。一个结构良好的文档应首先做到以下几点。l 文档注释应能增加代码的可读性编写注释的目的是使你、你的开发伙伴以及后续的开发人员更好地理解你的代码。SUN公司JAVA开发组的Nagle曾说过“如果程序不值得写文档的话，意味着代码也不值得运行”。l 避免文档的过度修饰六七十年代的COBOL语

6、言开发着有一种注释习惯，通常用星号画一个方盒子来填写注释。这样做的确很好看，但对于最终产品来讲没有太多的益处。应当注意文档中注释和代码的比例，代码的注释应当简洁、明了。l 在编码前就开始写文档 原则上讲，我们看一段代码总能发现它在做什么。例如，下面这段代码中，我们能分析出代码的行为，但不能真正看出它的确切语义。 If ( grandTotal = 1000.00) grandTotal = grandTotal*0.95; 在注释文档中应说明代码所表达的语义和编码设计思想，而不应只是就事论事的讲述代码的行为。1.3 如何使代码简洁l 为代码写注释文档l 将代码从逻辑上分段l 合理的使用空行l

7、遵守“30秒规则”，提高代码的可读性l 书写较短的代码行2 源文件的组织一个JAVA源文件是由用空白行和注释分隔开的很多部分组成的，通常文件长度应该小于2000行。2.1 Java源文件每一个Java源文件都包括一个公共的类或接口。当私有类或接口与公共类相关联的时候，通常可以将其与公共类放在同一个源文件当中。公共类应是文件中的第一个类或接口。Java源文件的组织结构如下：l 文件开始的注释段l Package和Import的声明l 类和接口声明2.1.1 文档开头的注释所有源文件的开始部分都要有一个C语言风格的注释段，列出本程序的类名、版本信息、日期、版权声明。如下所示。/* * Classn

8、ame * * Version information * * Date * * Copyright notice */2.1.2 Package和Import声明通常Java源文件中第一个非注释行是一个Package声明，然后是Import声明。如下所示。package java.awt;import java.awt.peer.CanvasPeer;2.1.3 类和接口声明下表描述了类和接口声明中的一些部分，按照其出现顺序列出：类和接口说明说明1Class/Interface 文档型注释/* * */2Class或Interface声明3Class或Interface的实现声明该段注释中应

9、该包括任何与类和接口有关的，但又不适于放在文档注释区中的注释说明4类静态变量变量出现的顺序为，首先公共变量，然后protected变量，然后是包package一级的变量，然后是私有变量5变量实例首先是公共变量，然后protected变量，然后是包package一级的变量，然后是私有变量6构造函数（Constructors）7方法方法应该按照功能而不是范围和可访问性来分类。例如，一个私有的类方法可以在两个公共的Instance方法的中间。这样做的目的是提高代码的可读性。3 文档的缩进规则文档中的缩进基本单位是4个空格。Tab键应当设置为4个空格键(WSAD中的缺省设置)。3.1 行的长度代码行的

10、长度应小于80个字符，否则不能被编辑和处理工具很好的处理。通常文档中代码例子的长度不超过70个字符。(在Jbuilder中可以设置，保持一致，80个字符)3.2 代码行的分割当一个表达式因太长等原因不适于单行放置的时候，可以根据下面的规则来进行分割：l 在逗号后面分割；l 在操作符前分割；l 应选择高一级的分割而不是低一级的分割；l 将换行后的表达式的开始部分与前一行的同一级表达式对齐；l 如果上述规则使得代码难读或代码集中在行的右侧，应4空格的缩进规则；(WSAD中的缺省设置，空一个TAB间隔)下面是一些方法调用行分割的例子someMethod(longExpression1, longEx

11、pression2, longExpression3,longExpression4, longExpression5);Type var = someMethod1(longExpression1,someMethod2(longExpression2,longExpression3)以上是好的格式，以下就不是很好。Type var = someMethod1(longExpression1,someMethod2(longExpression2,longExpression3)下面是两个算术表达式的换行分割的例子。LongName1 = longName2*( longName3 + lo

12、ngName4 longName5) + 4 * longName6; / 较好的分割方式LongName1 = longName2*( longName3 + longName4 longName5)+ 4 * longName6; / 尽量避免这种分割方式其中，第一方式的较好，因为换行分割点位于括号的外边，同第二种分割相比是分割的级别较高。当方法中参数很多时，提倡如下的书写：public void someMethod(Type longExpression1, Type longExpression2, Type longExpression3,Type longExpression4,

13、 Type longExpression5) . 同样，当IF语句或其他循环语句较长时，提倡如下的书写: if (condition1 & condition2 ) | (condition3 & condition4) | !(condition5 & condition6) doSomethingAboutIt();下面是3个可接受的表达式的书写方式alpha = (alongBooleanExpression) ? beta : gamma;alpha = (alongBooleanExpression) ? beta : gamma;alpha = (alongBooleanExpre

14、ssion) ? beta : gamma;4 代码的注释规则JAVA有三种注释方式。如下表所示。注释方式使用场合例 子文档型(Document)注 释这种注释放在程序代码中的，接口函数、类、成员函数和域的声明定义之前。文档型注释由javadoc来处理。如右图所示，为一个类创建一个外部说明文档。/* Customer- A customer is any person or organization that we sell services and products to. author S.W. Ambler*/C 风格的注释一般来说，用C风格的注释来说明一段代码是不合适的。 这种方式主要

15、用在维护和修改代码时，或者调试中临时关闭一段代码时使用。/* This code was commented out By J.T.Kirk on Dec 9,1997 because it was replaced by the prededing code. Delete it after two years if it is still not applicable. (the source code)*/单行注释一般在成员函数的内部采用单行注释，主要用来说明事务逻辑（business logic）、代码段、临时变量的声明定义。/Apply a 5% discount to all in

16、voices /over $1000 as defined by the Sarek/ generosity compaign started in / Feb. Of 19954.1 代码注释的基本原则l 注释应能使代码更加明确l 避免注释部分的过度修饰l 保持注释部分简单、明确l 在编码以前就应开始写注释l 注释应说明设计思路而不是描述代码的行为4.2 注释的运用JAVA程序有两类注释：一类是实现性注释（implementation comments），另一类是文档型注释（documentation comments）。其中，Implementation 注释有C和C+两种格式，/*.*/

17、 和/。文档型注释是JAVA程序所独有的，在/*.*/中限定。文档型注释能够被javadoc文件工具提取到HTML文件中。Implementation注释用于注释代码或者注释特殊的实现。文档型注释主要是描述代码段的说明，从一种非面向实现的角度来写给开发人员阅读读，这些开发人员可能手边并没有源代码。通常注释应该是给代码一个总的描述或者提供从代码本身不太容易看出的附加性信息。注释的内容应只与读代码和理解代码有关。例如，关于相应的包（package）是如何构建，以及存放在什么目录中，不应该包括在注释中。对代码中不太明显的设计意图进行说明是应该的，但也应避免对一些明显的信息进行重复说明，尽量避免那些随

18、着代码的维护会过时的注释。注意：过于频繁的注释常常意味着代码质量较低。但你觉得必须频繁添加注释时，应考虑重写该段代码了。注释内容不应封在星号（*）或者其它字母围成的矩形框中；注释中不应带有特殊注释字符如制表符（form-feed）和退格符（backspace）。4.3 Implementation注释的格式JAVA程序段中可以有4种形式的实现注释：块注释（block）、单行注释、后注释（trailing）、行尾注释(end-of-line)。4.3.1 块注释块注释用来提供文件、方法、数据结构和算法的描述。块注释主要用在每个文件和方法的开头部分，有时也可用在方法的中间。在一个函数和方法中的块注

19、释应该遵照缩进规则排列到说明对象的同一级深度。通常块注释前用一个空行和其它的代码段分开。/* * Here is a block comment. */另外，用/* - 开始的块注释能够被indent(1)识别出，作为块注释的开始。例如，/*- * Here is a block comment with some very special * formatting that I want indent(1) to ignore. * */注意： 如果你自己不用indent(1),你没有必要用/* -注释开始。4.3.2 单行注释单行注释应与其注释的代码处在同一缩进级别中。如果一个注释能写成单

20、行，那么没有必要写成块注释。单行注释前面应有一个空格。例如，if (condition) /* Handle the condition. */.4.3.3 后注释(trailing)(不提倡使用)一些非常短的注释可以加在代码的同一行内，但是应该把注释和代码分开足够大的间隔，以增加可读性。如果在一个小代码段中有多个后注释，那么应将其用TAB缩进对齐。If (a = 2) Return TRUE;/* special case */ else return isPrime(a);/*work only for odd a */4.3.4 行尾注释(End-of-line)“/”注释符能够将整行或

21、部分行注释掉，它不能用在连续的多行文本注释中。它可以用在将小段连续的代码注释掉。所有的3种风格如下所示。If (foo 1) / Do a double-flip.elsereturn false;/Explain why here(不提倡这样使用，应该单独作为一行放在前面)/ if (bar 1) / / Do a triple-flip././else/return false;/4.4 文档型注释(Documentation)JAVA SDK本身提供了较强的代码文档生成功能，只要代码中的注释符合一定的规则就可利用javadoc工具自动生成代码文档。Javadoc 是一种工具，它用于对一组

22、源文件中的声明和文档注释进行语法分析，并生成一组 HTML（HyperText Markup Language，超文本标记语言）页，描述类、内部类、接口、构造函数、方法和域。文档型注释与javadoc紧密相关，可通过灵活运用文档型注释让javadoc自动生成丰富详实的代码文档。Javadoc可从*.java源文件、包说明文件、概述说明文件，以及其它文件中提取信息生成文档。文档型注释(documentation)主要描述JAVA类、接口、构造器、方法和域。每一个文件注释的内容在/*.*/, 一个类和接口一个注释段。注释应该紧接着类声明的前面。文档型注释的格式是/*及其之后的空格都被javadoc

23、忽略，后续行中的第一个*也被忽略。/* * The Example class provides . */public class Example .注意：最上一级的类和接口是不缩进的，第一行是(/*)。其它的成员函数和构造模板要用4空格的缩进。如果需要对类、接口进行注释但是又不适于采用文档型注释，可以用块注释或者单行注释。例如，一个类的详细实现信息可以通过在类声明后的块注释来做。文档性注释不能放在一个方法和构造之内。4.4.1 位置源代码的文档型注释放在任何实体（类、接口、方法、属性、构造函数）的开头。注意：1、 只有紧挨着类、接口、方法、属性、构造函数声明的那块注释才被生成javadoc文

24、档，每个声明语句前只有一块注释可被javadoc识别。2、 函数内部的注释不会生成javadoc文档。例如下面例子中的注释因为放在了import语句之前，而无法被生成文档： /* * This is the class comment for the class Whatever. */ import com.sun; / MISTAKE - Important not to put import statement here public class Whatever 注释的第一句话每块文档型注释的第一句话应该是一个概括型语句，可简洁但完整地描述本块注释将要表达的意思。Javadoc将使用该

25、句文字作为成员方法的概述。注释内部的HTML标签文档型注释遵循HTML语法规则，可以在注释中插入任何想要的HTML标签以对注释进行格式化。从注释生成的文档中缺省是没有换行的，如需要在最终文档中体现换行，需要在注释中增加换行标签： /* * 查询指定条件上的线路配置集。 * 该方法是静态方法，无需实例化一个本类的对象即可调用本方法。 * param neName 网元的名字 * param cpn 表明需要查询哪个机框、板、端口上的信息。注意本方法不按机架 * 进行查询，因为一个机架上会有两个网元，所以CPN中的rack设为-1。按从细到粗的 * 顺序，CPN中的其它字段也可设置为-1，表示查询

26、仅精确到上一级单位。 * return 返回AdslLineConfProfileTable对象组成的Vector。 * */如需加粗某些文字：/* * This is a doc comment. * see java.lang.Object */javadoc自身的标签javadoc提供了若干种自定义标签，充分运用这些标签可使生成的文档结构更合理，实用性更强。Javadoc标签以开头，且是大小写敏感的。包括以下几种标签：author 、docRoot、deprecated、exception、link、param、return、see、serial、serialData、serialFie

27、ld、since、throws、version。下面简要介绍几种很常用且比较重要的标签。author name-text将代码作者的名字生成到文档中。param parameter-name description描述方法的参数return description描述返回值see reference增加一个See Also的链接。4.4.2 javadoc标签的使用位置标签概述文档，一般是overview.htmlsee、link、since包文档see、link、since、deprecated类和接口文档see、link、since、deprecated、author、version属性文

28、档see、link、since、deprecated、serial、serialField构造函数或方法文档see、link、since、deprecated、param、return、throws (exception)、serialData尽量不要使用括号中的标签，如：exception；因为在JDK1.2中已经用括号前面的替代了。4.4.3 加入样例代码对于较复杂的类或方法，最好在其注释文档中增加一段如何使用本类（方法）的例子代码。由于javadoc生成的文档会忽略空格和换行，应在样例代码段前后加上标签：/* * A class representing a window on the

29、screen. * For example: * * Window win = new Window(parent); * win.show(); * * * author Sami Shaio * version %I%, %G% * see java.awt.BaseWindow * see java.awt.Button */class Window extends BaseWindow .4.4.4 生成javadoc文档下面给出一个简单的批处理文件用于生成javadoc文档：del filelist.txtdir /b /s .ems5100src*.java filelist.tx

30、tdir /b /s .emsbasesrc*.java filelist.txtjavadoc -windowtitle IPMS源程序文档(JavaDOC) -private filelist.txt另外，Javadoc 有许多有用的选项，有些相对其他更为常用。下面是实际中我们用来在 Java 平台 API 上运行 javadoc 的命令，它使用了 makefile 变量（除了未列出所有要建文档的包之外）。javadoc -sourcepath /jdk/src/share/classes /* 源文件路径 */ -d /jdk/build/api /* 目的目录 */ -use /* 添

31、加“用法”文件 */ -splitIndex /* 分割索引 A-Z */ -windowtitle $(WINDOWTITLE) /* 添加窗口标题 */ -doctitle $(DOCTITLE) /* 添加文档标题 */ -header $(HEADER) /* 添加运行页眉文本 */ -bottom $(BOTTOM) /* 添加底部文本 */ -group $(GROUPCORE) /* 概述页的核心标题 */ -group $(GROUPEXT) /* 概述页的扩展标题 */ -overview overview-core.html /* 概述文本 */ -J-Xmx180m /*

32、 180MB 内存 */ java.lang java.lang.reflect /* 要建立其文档的包 */ java.util java.io java.appletWINDOWTITLE = Java 平台 1.2 最终 API 规范DOCTITLE = JavaTM Platform 1.2 Final API SpecificationHEADER = Java Platform 1.2FinalBOTTOM = a href= 提交 bug 或功能 Java 是 Sun Microsystems , Inc 在美国和其他国家的商标或注册商标。Copyright 1993-1998

33、Sun Microsystems, Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A.保留所有权利。GROUPCORE = 核心包 java.*:com.sun.java.*:org.omg.*GROUPEXT = 扩展包 javax.*如果省略 -windowtitle 选项，则 javadoc 将文档标题复制到窗口标题。-windowtitle 选项是没有必要的，除非文档标题包含 HTML 标记。5 变量的声明5.1 每行变量声明个数通常JAVA代码中一行只声明一个变量。int level;/ indentation

34、 levelint size;/ size of table对比 int level, size;注意：上面的例子是在变量类型和定义之间用一个空格；实际中也可以用TAB键。例如，int level;/ 缩进层次intsize;/ 表的大小ObjectcurrentEntry;/ 当前被选的表入口5.2 变量初始化应在一个变量声明的时就对它进行初始化工作。5.3 变量声明的位置变量声明只应该放在代码段的开始部分。代码段是指花括号所包括的区域。严禁到使用时才声明变量。Void myMethod() int int1 = 0;/beginning of method block If (condit

35、ion) int int2 = 0;/ beginning of “if” block . 唯一的例外是for循环中的循环变量，如for (int i = 0; i maxLoops; i+) . 为了避免局部变量被高一级的变量所覆盖，应避免在局部代码块中采用同样的变量名称。例如，int count;.myMethod() if (condition) int count;/ 应避免这种情况.5.4 类和接口的声明当编写JAVA的类和接口是应该遵循下列格式规则：l 在方法名称和其后的括号（）之间没有空格;l 声明类和接口时，表示代码块开始的花括号”“处在声明的同一行的末尾；l 花括号”“应该与

36、相应的花括号”“所在的行缩进对齐；l 方法与方法之间用空行隔开；class Sample extends Object int ivar1;int ivar2;Sample(int i, int j) ivar1 = i;ivar2 = j;/ 空行int emptyMethod() ;6 语句6.1 简单语句每一行应该只包括一个语句，例如：argv+;/正确argc+;/正确argv+; argc-;/错误6.2 复合语句复合语句是指用一对花括号包围起来的任意数量的简单语句语句。l 括起来的语句应该比复合语句缩进至少一层。l 开始括号应该在复合语句末尾；结束括号应该在新的一行并且和复合语句括

37、号的开始行对齐。l 当它们作为控制流程的一部分的时候，应该用括号把所有的复合语句括起来，即使只有一句简单语句，比如if-else或者for语句。这样可以更方便的加入语句而不会引起由于忘掉加括号而引起的偶然性的错误。6.3 返回语句带值的返回语句不需要用圆括号，除非有时不得不用括号使返回结构更加明显。例如：return;return myDisk.size( );return (size ? size : defaultSize);6.4 if，if-else，if else-if else语句if-else类语句有如下几种形式：if (condition) statements;if (con

38、dition) statements; else statements;if (condition) statements; else if (condition) statements; else statements;注意：if语句一定要用花括号；要避免以下混淆形式：if (condition) /要避免这种对花括号的忽略！statement;6.5 for语句for语句形式如下：for (initialization; condition; update) statements;一个空的for循环语句的形式如下：for (initianlization; condition; updat

39、e);当for循环的initianlization部分和update部分中有多个用逗号隔开的变量时，通常变量的数量不应该超过3个。如果必要的话，可以在for循环的之前（initianlization部分前）或者在循环的尾部（update部分）使用单独的语句来说明。6.6 while 循环语句一个while语句结构如下：while (condition) statements;下面是一个空的while循环语句：while (condition);6.7 do-while 语句一个do-while 循环语句的形式如下：do statements; while (condition);6.8 swi

40、tch语句一个switch语句的结构如下：switch (conditon) case ABC:statements;/* falls through */case DEF:statements;break;case XYZ:statements;break;default:statements;break;每一个switch语句中应该包括一个default case语句。6.9 try-catch 语句try-catch语句有以下格式：try statements; catch (ExceptionClass e) statements;try-catch语句也可以跟随finally，它总是被执行，而不受异常是否抛出的影响。try statements; catch (ExceptionClass e) statements; finally statements;7 空行和空格的使用7.1 空行的使用