中央研究院Java编程规范.docx

1、中央研究院Java编程规范卷号卷内编号密级分类:COD使用者:设计员、实施员托普集团,2009中央研究院Java编程规范Version 2.0作者:Administrator文档信息标题:中央研究院Java编程规范作者:Administrator创建日期:2009-03-26上次更新日期:2010-12-22版本:2.0部门名称:中央研究院文档状态文档状态草稿 正式文档评审人员SEPG评审时间2001/9/30修订文档历史记录日期版本说明作者2001-9-4初稿张玮2001-09-171.0张玮2001-09-3020张玮 中央研究院Java编程规范1.简介本文提供一整套编写高效可靠的 Jav

2、a 代码的标准、约定和指南。它们以安全可靠的软件工程原则为基础，使代码易于理解、维护和增强。而且，通过遵循这些程序设计标准，你作为一个 Java 软件开发者的生产效率会有显著提高。经验证明，若从一开始就花时间编写高质量的代码，则在软件开发阶段，对代码的修改要容易很多。最后，遵循一套通用的程序设计标准将带来更大的一致性，使软件开发团队的效率明显提高。目的本文档用于指导编码，并确立起一个易于理解、维护，并同软件过程及过程工具紧密集成的编码约定。范围本文档对中央研究院所有采用Java作为开发语言的项目适用。定义、首字母缩写词和缩略语注释率 注释在代码中所占比例。语句注释 在源文件中C语言风格注释行内

3、注释文档注释参考资料RUP2000中文版的Java 编程指南Draft Java Coding Standard Doug LeaJavasoft coding standardsThe Infospheres Java Coding Standard概述本文档共分为六部分：第一部分为简介；第二部分程序设计的一些普遍标准；为第三部分为对Java源文件的分结构说明；第四部分为描述与工具的集成；第五部分为本文档所规定的一些数据；第六部分为建议的最佳实践。原则本节描述描述制作本文档时所采取的原则，这些原则是一开始就确定的，并且贯穿在整个文档中。以下的原则的排列是按优先级进行的，这也就是说，在原则之间

4、有冲突时，应该优先考虑排在前面的项目。便于阅读从软件工程的角度上来看，代码让人更容易看懂远比让机器看懂更有价值得多。首先代码永远不进行维护似乎是很少发生的，其次，就算代码永远不进行维护，至少为了代码重用的目的也需要其他人能够很容易地看懂代码。这里有一条30秒原则，即其他程序员能在30秒内完全读懂你的方法，理解做什么，为什么及怎样做的。与工具集成鉴于开发过程大量地集成了工具，因此要与整个开发过程结合就必须考虑怎样使代码与工具和平相处并配合密切。与工具集成同时可以增加生产力，并减少由于人工转换过程中引入的错误。JavaDoc与JavaDoc的集成可使文档的说明自动生成并可表现为多种形式。Rose考

5、虑到整个开发过程使用了RUP，因此与其所提供的工具Rose的集成是很有价值的。与Rose的集成是指保存在Rose中的设计模型可正向生成符合本规范的代码，也可从符合本规范的代码中反向生成Rose的设计模型。配置工具与配置工具的集成是指代码规范与配置工具的要求不冲突。编码工具与编码工具的集成是指代码可用编码工具自动完成一部分内容，这也是提高生产力的一种努力。便于调试便于调试是指在规范的约束下，应该不影响调试。便于写作这条原则是说明不要花时间去进行格式的编排，如将注释换一行书写，而不是花时间去调整让注释右对齐。让实施员集中精力于该干的事，而诸如注释的好看与否等等则不应该是编码人员关心的事。减少重复同

6、样的一个信息不应该在多个地方出现。原则约定便于阅读缩进适当地增加括号折行行宽限制与工具集成对JavaDoc的注释支持对Rose的注释支持JBuilder的模板文件及配置便于调试一行一条语句便于写作注释与语句不同行减少重复同样的内容不在多处重复表格 1原则及约定对应表2.程序设计标准本节的大部分内容是从参考资料1中剪裁而来，如果需要更详细的内容，请参见参考资料1中的程序设计标准的一节。Java 的程序设计标准很重要，原因在于它将提高开发团队各成员的代码的一致性。一致性的提高会使代码更易理解，这意味着它更易开发和维护。从而降低了应用程序的总开发成本。通用命名约定我们将在整个标准中讨论命名约定，所以

7、让我们先讨论几个基本点：采用该领域的术语如果用户称他们的“客户” (clients) 为“顾客” (customers)，那么就采用术语 Customer 来命名这个类，而不用 Client。许多程序开发者会犯的一个错误是，不去使用工业或领域里已经存在着很完美的术语时，却生造出一些普通词汇。大小写常量的字母全部大写，单词之间用一个下划线字符(_)进行分隔。除常量外的命名采用大小写混合，提高名字的可读性。一般采用小写字母，但是类和接口的名字的首字母，以及任何中间单词的首字母应该大写。使用可以准确说明的英文描述符例如，采用类似 firstName，grandTotal 或 CorporateCus

8、tomer 这样的名字。虽然象 x1，y1 或 fn 这样的名字很简短，输入起来容易，但是我们难以知道它们代表什么、结果是什么含义，因而使代码难以理解、维护和改进。下划线的使用避免使用下划线作为名字的首末字母，以下划线为首末字母的名字通常为系统保留，除预处理定义之外，一般不用作用户命名。更重要的是，下划线经常造成麻烦而且难输入，所以尽量避免使用。因此建议下划线只用在常量的命名的单词中间作分隔符。避免使用长名字命名不要超过标识符最大字符数，标识符字符数请参见数据一节。虽然 PhysicalOrVirtualProductOrService 看起来似乎是个不错的类名，但是这个名字太长了，应该考虑重

9、新给它起个短一点的名字，比如象 Offering。标识符的命名标识符类型命名规则ExamplesPackages 每一个包的名称总是小写，规则采用类似于TCP/IP中域名的反序，即以com, edu, gov, mil, net, org, 或ISO 3166,1981中定义的两位国家代码开始，接着是组织名称，在此处以com.topgroup开始，接着是，其后的部分由项目自已定义。com.topgroup.eng com.topgroup.report.v2com.topgroup.jdmClasses 类名必须是名词，大小写遵照前面定义的大小写规则（即每个单词首字母大写）。类名应该简单清晰。

10、不要使用除通用的计算机缩写或通用的领域缩写外的其它缩写。class Raster;class ImageSprite; Interfaces 同类名规则。interface RasterDelegate;interface Storing; Methods 方法应该是动词，或以动词开始的动宾结构短语，大小写遵照前面定义的大小写规则(即除第一个单词外，每个单词的首字母大写)。run();runFast();getBackground(); Variables 变量名应该短而准确并便于记忆。大小写遵照前面定义的大小写规则(即除第一个单词外，每个单词的首字母大写)。除了临时使用的如循环变量等以外，不

11、要使用单字符的变量名。对于使用单字符的临时变量名，建议循环变量名用i,j,k，n表示整数，c,d,e表示字符。int i;char c;float myWidth;Constants 全部大写，单词之间用下划线分隔。static final int MIN_WIDTH = 4; static final int MAX_WIDTH = 999; static final int GET_THE_CPU = 1; 界面元素的命名界面元素是指如Form，控件等变量及类的命名。界面元素命名的一条基本原则是界面元素的命名应简单而不产生混淆，一般情况下，界面元素的命名直接参照变量命名规则，但若发生了混淆

12、或估计会发生混淆的界面元素，则可以在该元素的后加元素类型的后缀，后缀的生成规则是：1、若元素类型是标准的Swing类型，则去掉类名”J”字符后的部分为元素类型名2、若元素类型是标准的AWT类型，则直接使用类名3、如果元素类型不是标准的Swing或AWT类型，元素类型的后缀使用其Swing或AWT的基类进行命名。如：自定义了class MyPanel extends JPanel，则若有MyPanel的元素，则元素后缀为Panel。下表给出了基本的元素类型后缀：类型后缀例JPanelPanellistPanelJButtonButtondelButtonJFrameFramemainFrameJ

13、InternalFrameFrame或InternalFramewelcomeFrame,welcomeInternalFrameJCheckBoxCheckBoxJ非强制的一些命名规则类型规则例抽象类以Abstract开始AbstractDjinn, AbstractCat, AbstractClass, AbstractPlayerFactory类以Factory结束DjinnFactory, CatFactory, ClassFactory, PlayerFactor实现类以Impl结束DjinnImpl, CatImpl, ClassImpl, PlayerImplException以

14、Exception结束DjinnException, CatException, ClassException, PlayerExceptionInterface以Interface结束或加-able后缀DjinnInterface, CatInterface, Runnable, RemoteLoadable通用格式一种提高代码可读性的方法是给代码分段，换句话说，就是在代码块内让代码缩进。所有在括号和之内的代码，构成一个块。基本思想是，块内的代码都应统一地缩进去一个单位。圆括号在表达式、方法调用及方法声明中圆括号“(”后及“)”前不应该有空格。缩进同级之间在同一个缩进位置。下一级与上一级之间

15、需要缩进。每一级缩进空格数请参见数据一节。空白行在代码中使用空白。在 Java 代码中加入几个空行，也叫空白，将代码分为一些小的、容易理解的部分，可以使它更加可读。建议采用一个空行来分隔代码的逻辑组，例如控制结构，采用两个空行来分隔方法定义。没有空白的代码很难读，很难理解。包和引入之间加一个空行不同可见性的变量定义之间加一个空行方法定义之间加一个空行不同可见性的方法组定义之间多加一个空行空格关键字与其后紧挨的括号之间应有一个空格进行分隔。参数列表的逗号之后应有一个空格进行分隔。大括号开始之前应有一个空格进行分隔。所有的二元操作符的前后均应有一个空格，二元操作符的例子有加号，除号，等于符号，赋值

16、符号等。for的每一个语句之间应有空格，即for (expr1; expr2; expr3)强制类型转换的括号之后应有一个空格。如myMethod(byte) aNum, (Object) x);myMethod(int) (cp + 5), (int) (i + 3) + 1);行宽行宽不得超过最大行宽，超过最大行宽就需要折行，最大行宽请参见数据一节。原理：行宽超过最大行宽往往需要用横向滚动条，影响阅读，而最大行宽之内的字符数在大多数阅读器中均能方便地进行阅读及打印。折行当一行装不下内容时，需要对这些内容进行折行，折行时遵守以下规则：在分号处折行在操作符前折行操作符包括+，-，*，/，左括号

17、，逗号，”&”，”|”，问号,冒号，例外的情况是在逗号后折行。例：someMethod(longExpression1 , longExpression2 , longExpression3 , longExpression4, longExpression5); var = someMethod1(longExpression1,someMethod2(longExpression2,longExpression3);有多个可以选择的地方时，选择层次较高的进行折行同一层次是指在表达式树中同一级（同一个括号内），层次较高是指在表达式树中较高的一级，以下两个例子可以说明这个规则。longName

18、1 = longName2 * (longName3 + longName4 - longName5)+ 4 * longname6; / PREFERlongName1 = longName2 * (longName3 + longName4- longName5) + 4 * longname6; / AVOID将新行与上一行的同一级的表达式的开始处对齐此处同一级的含义同上。方法定义的折行如果方法定义太长，可以在参数处进行折行，下一行可以遵守同级开始处对齐原则。 如：/同级开始处对齐原则someMethod(int anArg, Object anotherArg, String yetA

19、notherArg,Object andStillAnother) ./比上一行缩进一级原则private static synchronized horkingLongMethodName(int anArg, Object anotherArg, String yetAnotherArg, Object andStillAnother) .简单地缩进一级在使用以上原则时，如果出现太深的缩进，如括号开始处可能在行末附近，这时，只是简单地在上一行的开始处缩进一级。注释Java 注释语句类型 Java 有三种注释语句风格：以 /* 开始， */ 结束的文档注释，以 /* 开始，以 */ 结束的C

20、语言风格注释，以及以 / 开始，代码行末尾结束的单行注释。下表是对各类注释语句建议用法的一个概括，也给出了几个例子。注释语句类型用法示例文档注释在接口、类、方法和字段声明之前紧靠它们的位置用文档注释进行说明。文档注释由 javadoc 处理，为一个类生成外部注释文档，如下所示。/* Customer（顾客）顾客是指作为我们的服务及产品的销售对象的任何个人或组织。author S.W. Ambler*/C 语言风格注释采用 C 语言风格的注释语句将无用的代码注释掉。保留这些代码是因为用户可能改变想法，或者只是想在调试中暂时不执行这些代码。/* 这部分代码已被它前面的代码替代，所以于 1999 年

21、6 月 4 日被 B. Gustafsson 注释掉。如果两年之后仍未用这些代码，将其删除。. . . （源代码）*/单行注释在方法内部采用单行注释语句对业务逻辑、代码片段和临时变量声明进行说明。/ 因为让利活动 / 从 1995 年 2 月开始，/ 所以给所有超过 $1000 的/ 发货单 5% 的折扣。快速浏览 javadoc Sun 公司的 Java Development Kit (JDK) 中有一个名为 javadoc 的程序。它可以处理 Java 的源代码文件，并且为 Java 程序产生 HTML 文件形式的外部注释文档。Javadoc 支持一定数目的标记，标识注释文档中各段起始位

22、置的保留字。详情请参考 JDK javadoc 文档。本规范支持并且要求有Javadoc的注释标记，该标记可由工具自动生成也可由手工制作。标记用于目的author name类、 接口说明特定某一段程序代码的作者。每一个作者各有一个标记。deprecated类、 方法说明该类的应用程序编程接口 (API) 已被废弃，因此应不再使用。exception name description方法说明由方法发出的异常。一个异常采用一个标记，并要给出异常的完整类名。param name description方法用来说明传递给一个方法的参数，其中包括参数的类型/类和用法。每个参数各有一个标记。return

23、description方法若方法有返回值，对该返回值进行说明。应说明返回值的类型/类和可能的用途。since类、方法说明自从有 JDK 1.1 以来，该项已存在了多长时间。see ClassName类、接口、方法、字段在文档中生成指向特定类的超文本链接。可以并且应该采用完全合法的类名。see ClassName#member functionName类、接口、方法、字段在文档中生成指向特定方法的超文本链接。可以并且应该采用完全合法的类名。version text类、接口说明特定一段代码的版本信息。按目的分的注释类型注释可按其目的分为外部注释、业务逻辑注释及其它注释。业务逻辑注释是指在类的方法中

24、用于解释业务逻辑的注释，外部注释是指不在类的方法中，是用于对外解释类或类的接口的注释。变量注释是指不用于外部注释中，对局部变量或私有类变量等变量的注释。业务逻辑注释在代码块（如类的方法，静态方法等）中用于解释业务逻辑的注释称为业务逻辑注释，除特殊情况外，业务逻辑注释一般采用单行注释的方式。代码数，代码数即语句数，不包括变量定义，与代码行数不同。代码数可用自动化工具获得。注释数为针对于语句的注释数。注释数与注释的行数不同，在两条语句之间的注释，不管行数多少，都算作一个注释。注释率=注释数/代码数*100%。每个方法的注释率的下限请参见数据一节，但语句数少于3句的除外。外部注释不在代码块中，用于对

25、外解释类或类的接口的注释称为外部注释。外部注释包括类的内容注释、公共方法及变量注释、保护方法及变量注释、包方法及变量注释。除非特殊情况，外部注释最好采用内容注释的方式。外部注释的注释率=内容注释数/定义数*100%。其中定义数是指公用的类或类的接口的数量。外部注释的注释率的下限请参见数据一节，如为100%，则每一个公共的、保护的、包的方法和变量都应加一个内容注释。原理：每一个公共、保护及包方法及变量都可能被其它人用到，因此关于该项的说明必须有。变量注释不用于外部注释中，对局部变量或私有类变量等变量的注释称为变量注释。变量注释的注释率=注释数/变量数*100%。变量注释的注释率的下限请参见数据一

26、节。3.源文件内容每个Java源文件只包含一个公共的类或接口，这是Sun公司的规定。当该公共类附带有私有类或接口时，可以把它们放在该公共类的同一个文件，但公共类必须出现在它们前面。源文件由以下三部分组成：文件头注释部分包及引入部分类及接口定义部分文件头注释部分每个Java源文件必须以一个C语言风格的注释开始，该注释包括文件名，版本信息，日期，变更记录及版权声明。参考格式如下：/* * * * Version information * * Date * * Copyright notice */文件名记录源文件名（不包括路径）。版本信息版本信息可选，但如果有的话，必须与配置系统的版本信息兼容。

27、变更记录变更记录包含变更日期、变更人和变更内容。版权声明版权声明是必须的，其内容必须包括：公司年份可用如下格式：Copyright 2000-2001 Topgroup. All Rights Reserved.包及引入部分Java源文件的第一条非注释行为package语句，包后加一空行，之后可以是一个或多个import语句，例如：package java.awt;import java.awt.peer.CanvasPeer;类及接口定义部分类及接口定义部分开始于一个内容注释以说明类及接口的功能、环境、使用方法等说明。类或接口与类或接口之间用一个空行间隔。变量定义变量定义包括类变量定义及局部

28、变量定义。位置这两种变量定义都应该在其任用域的一开始处定义，即对于类变量，在类的开始处的大括号之后就对它进行定义，对于方法内的局部变量，在方法定义开始处的大括号之后进行定义。尽量不要在方法内某一块中定义局部变量。静态变量在最前，按可见性从高到低排列。若有静态块，则静态块在其后，其后是非静态的类变量，按可见性从高到低排列，即按公共、保护、包、私有的顺序进行排列，不同可见性的类变量组之间应用一个空行进行分隔。格式公共的类变量前必须有一个内容注释说明它。每个变量定义应该占据一行，并且应该对该变量进行注释，但建议不要进行行尾注释，最好在变量定义之前进行注释。如：/ indentation leveli

29、nt level;/ size of tableint size;就好于int level, size;两个同样可见性的变量定义之间不要有空行。类型不同的变量不要在同一行中，如：int foo, fooarray;/避免尽量在定义处对变量进行初始化方法定义两个方法定义之间用一个空行分隔。方法名与参数引导符圆括号之间不要有空格，方法顺序为：构造方法finalize方法初始化方法static方法公共方法保护方法包方法私有方法方法定义部分开始于一个内容注释以说明该方法的功能、环境、使用方法等所有重要的有助于理解方法的信息，尽可能在其中加入Javadoc标记，当然，这件事有一部分也可能是由设计人员完成的。有返回值的必须加return标记，有参数的必须对每一个参数加param标记，有错误的必须加exception标记，尽量加see标记。这些信息包含但不仅仅局限于以下内容： 方法说明方法说明对方法整体进行说明，包括以下内容：3.1.1.1.1 成员函数做什么以及它为什么做这个通过给一个方法加注释，让别人更加容易判断他们是否可以复用代码。注释出方法为什