中央研究院Java编程规范Word格式.docx
《中央研究院Java编程规范Word格式.docx》由会员分享，可在线阅读，更多相关《中央研究院Java编程规范Word格式.docx（27页珍藏版）》请在冰点文库上搜索。
它们以安全可靠的软件工程原则为基础，使代码易于理解、维护和增强。
而且，通过遵循这些程序设计标准，你作为一个Java软件开发者的生产效率会有显著提高。
经验证明，若从一开始就花时间编写高质量的代码，则在软件开发阶段，对代码的修改要容易很多。
最后，遵循一套通用的程序设计标准将带来更大的一致性，使软件开发团队的效率明显提高。
目的
本文档用于指导编码，并确立起一个易于理解、维护，并同软件过程及过程工具紧密集成的编码约定。
范围
本文档对中央研究院所有采用Java作为开发语言的项目适用。
定义、首字母缩写词和缩略语
注释率注释在代码中所占比例。
语句
注释在源文件中
C语言风格注释
行内注释
文档注释
参考资料
RUP2000中文版的《Java编程指南》
DraftJavaCodingStandardDougLea
Javasoftcodingstandards
TheInfospheresJavaCodingStandard
概述
本文档共分为六部分：
第一部分为简介；
第二部分程序设计的一些普遍标准；
为
第三部分为对Java源文件的分结构说明；
第四部分为描述与工具的集成；
第五部分为本文档所规定的一些数据；
第六部分为建议的最佳实践。
原则
本节描述描述制作本文档时所采取的原则，这些原则是一开始就确定的，并且贯穿在整个文档中。
以下的原则的排列是按优先级进行的，这也就是说，在原则之间有冲突时，应该优先考虑排在前面的项目。
便于阅读
从软件工程的角度上来看，代码让人更容易看懂远比让机器看懂更有价值得多。
首先代码永远不进行维护似乎是很少发生的，其次，就算代码永远不进行维护，至少为了代码重用的目的也需要其他人能够很容易地看懂代码。
这里有一条30秒原则，即其他程序员能在30秒内完全读懂你的方法，理解做什么，为什么及怎样做的。
与工具集成
鉴于开发过程大量地集成了工具，因此要与整个开发过程结合就必须考虑怎样使代码与工具和平相处并配合密切。
与工具集成同时可以增加生产力，并减少由于人工转换过程中引入的错误。
JavaDoc
与JavaDoc的集成可使文档的说明自动生成并可表现为多种形式。
Rose
考虑到整个开发过程使用了RUP，因此与其所提供的工具Rose的集成是很有价值的。
与Rose的集成是指保存在Rose中的设计模型可正向生成符合本规范的代码，也可从符合本规范的代码中反向生成Rose的设计模型。
配置工具
与配置工具的集成是指代码规范与配置工具的要求不冲突。
编码工具
与编码工具的集成是指代码可用编码工具自动完成一部分内容，这也是提高生产力的一种努力。
便于调试
便于调试是指在规范的约束下，应该不影响调试。
便于写作
这条原则是说明不要花时间去进行格式的编排，如将注释换一行书写，而不是花时间去调整让注释右对齐。
让实施员集中精力于该干的事，而诸如注释的好看与否等等则不应该是编码人员关心的事。
减少重复
同样的一个信息不应该在多个地方出现。
约定
缩进
适当地增加括号
折行
行宽限制
对JavaDoc的注释支持
对Rose的注释支持
JBuilder的模板文件及配置
一行一条语句
注释与语句不同行
同样的内容不在多处重复
表格1原则及约定对应表
2.程序设计标准
本节的大部分内容是从参考资料1中剪裁而来，如果需要更详细的内容，请参见参考资料1中的程序设计标准的一节。
Java的程序设计标准很重要，原因在于它将提高开发团队各成员的代码的一致性。
一致性的提高会使代码更易理解，这意味着它更易开发和维护。
从而降低了应用程序的总开发成本。
通用命名约定
我们将在整个标准中讨论命名约定，所以让我们先讨论几个基本点：
采用该领域的术语
如果用户称他们的“客户”（clients）为“顾客”（customers），那么就采用术语Customer来命名这个类，而不用Client。
许多程序开发者会犯的一个错误是，不去使用工业或领域里已经存在着很完美的术语时，却生造出一些普通词汇。
大小写
常量的字母全部大写，单词之间用一个下划线字符（_）进行分隔。
除常量外的命名采用大小写混合，提高名字的可读性。
一般采用小写字母，但是类和接口的名字的首字母，以及任何中间单词的首字母应该大写。
使用可以准确说明的英文描述符
例如，采用类似firstName，grandTotal或CorporateCustomer这样的名字。
虽然象x1，y1或fn这样的名字很简短，输入起来容易，但是我们难以知道它们代表什么、结果是什么含义，因而使代码难以理解、维护和改进。
下划线的使用
避免使用下划线作为名字的首末字母，以下划线为首末字母的名字通常为系统保留，除预处理定义之外，一般不用作用户命名。
更重要的是，下划线经常造成麻烦而且难输入，所以尽量避免使用。
因此建议下划线只用在常量的命名的单词中间作分隔符。
避免使用长名字
命名不要超过标识符最大字符数，标识符字符数请参见数据一节。
虽然PhysicalOrVirtualProductOrService看起来似乎是个不错的类名，但是这个名字太长了，应该考虑重新给它起个短一点的名字，比如象Offering。
标识符的命名
标识符类型
命名规则
Examples
Packages
每一个包的名称总是小写，规则采用类似于TCP/IP中域名的反序，即以com,edu,gov,mil,net,org,或ISO3166,1981中定义的两位国家代码开始，接着是组织名称，在此处以com.topgroup开始，接着是<
项目英文简写>
，其后的部分由项目自已定义。
com.topgroup.eng
com.topgroup.report.v2
com.topgroup.jdm
Classes
类名必须是名词，大小写遵照前面定义的大小写规则（即每个单词首字母大写）。
类名应该简单清晰。
不要使用除通用的计算机缩写或通用的领域缩写外的其它缩写。
classRaster;
classImageSprite;
Interfaces
同类名规则。
interfaceRasterDelegate;
interfaceStoring;
Methods
方法应该是动词，或以动词开始的动宾结构短语，大小写遵照前面定义的大小写规则（即除第一个单词外，每个单词的首字母大写）。
run（）;
runFast（）;
getBackground（）;
Variables
变量名应该短而准确并便于记忆。
大小写遵照前面定义的大小写规则（即除第一个单词外，每个单词的首字母大写）。
除了临时使用的如循环变量等以外，不要使用单字符的变量名。
对于使用单字符的临时变量名，建议循环变量名用i,j,k，n表示整数，c,d,e表示字符。
inti;
charc;
floatmyWidth;
Constants
全部大写，单词之间用下划线分隔。
staticfinalintMIN_WIDTH=4;
staticfinalintMAX_WIDTH=999;
staticfinalintGET_THE_CPU=1;
界面元素的命名
界面元素是指如Form，控件等变量及类的命名。
界面元素命名的一条基本原则是界面元素的命名应简单而不产生混淆，一般情况下，界面元素的命名直接参照变量命名规则，但若发生了混淆或估计会发生混淆的界面元素，则可以在该元素的后加元素类型的后缀，后缀的生成规则是：
1、若元素类型是标准的Swing类型，则去掉类名”J”字符后的部分为元素类型名
2、若元素类型是标准的AWT类型，则直接使用类名
3、如果元素类型不是标准的Swing或AWT类型，元素类型的后缀使用其Swing或AWT的基类进行命名。
如：
自定义了classMyPanelextendsJPanel，则若有MyPanel的元素，则元素后缀为Panel。
下表给出了基本的元素类型后缀：
类型
后缀
例
JPanel
Panel
listPanel
JButton
Button
delButton
JFrame
Frame
mainFrame
JInternalFrame
Frame或InternalFrame
welcomeFrame,welcomeInternalFrame
JCheckBox
CheckBox
J
非强制的一些命名规则
规则
抽象类
以Abstract开始
AbstractDjinn,AbstractCat,AbstractClass,AbstractPlayer
Factory类
以Factory结束
DjinnFactory,CatFactory,ClassFactory,PlayerFactor
实现类
以Impl结束
DjinnImpl,CatImpl,ClassImpl,PlayerImpl
Exception
以Exception结束
DjinnException,CatException,ClassException,PlayerException
Interface
以Interface结束或加-able后缀
DjinnInterface,CatInterface,Runnable,RemoteLoadable
通用格式
一种提高代码可读性的方法是给代码分段，换句话说，就是在代码块内让代码缩进。
所有在括号{和}之内的代码，构成一个块。
基本思想是，块内的代码都应统一地缩进去一个单位。
圆括号
在表达式、方法调用及方法声明中圆括号“（”后及“）”前不应该有空格。
同级之间在同一个缩进位置。
下一级与上一级之间需要缩进。
每一级缩进空格数请参见数据一节。
空白行
在代码中使用空白。
在Java代码中加入几个空行，也叫空白，将代码分为一些小的、容易理解的部分，可以使它更加可读。
建议采用一个空行来分隔代码的逻辑组，例如控制结构，采用两个空行来分隔方法定义。
没有空白的代码很难读，很难理解。
包和引入之间加一个空行
不同可见性的变量定义之间加一个空行
方法定义之间加一个空行
不同可见性的方法组定义之间多加一个空行
空格
关键字与其后紧挨的括号之间应有一个空格进行分隔。
参数列表的逗号之后应有一个空格进行分隔。
大括号开始之前应有一个空格进行分隔。
所有的二元操作符的前后均应有一个空格，二元操作符的例子有加号，除号，等于符号，赋值符号等。
for的每一个语句之间应有空格，即for（expr1;
expr2;
expr3）
强制类型转换的括号之后应有一个空格。
如
myMethod（（byte）aNum,（Object）x）;
myMethod（（int）（cp+5）,（（int）（i+3））
+1）;
行宽
行宽不得超过最大行宽，超过最大行宽就需要折行，最大行宽请参见数据一节。
原理：
行宽超过最大行宽往往需要用横向滚动条，影响阅读，而最大行宽之内的字符数在大多数阅读器中均能方便地进行阅读及打印。
当一行装不下内容时，需要对这些内容进行折行，折行时遵守以下规则：
在分号处折行
在操作符前折行
操作符包括+，-，*，/，左括号，逗号，”&
&
”，”||”，问号,冒号，例外的情况是在逗号后折行。
例：
someMethod（longExpression1,longExpression2,longExpression3,
longExpression4,longExpression5）;
var=someMethod1（longExpression1,
someMethod2（longExpression2,
longExpression3））;
有多个可以选择的地方时，选择层次较高的进行折行
同一层次是指在表达式树中同一级（同一个括号内），层次较高是指在表达式树中较高的一级，以下两个例子可以说明这个规则。
longName1=longName2*（longName3+longName4-longName5）
+4*longname6;
//PREFER
longName1=longName2*（longName3+longName4
-longName5）+4*longname6;
//AVOID
将新行与上一行的同一级的表达式的开始处对齐
此处同一级的含义同上。
方法定义的折行
如果方法定义太长，可以在参数处进行折行，下一行可以遵守同级开始处对齐原则。
//同级开始处对齐原则
someMethod（intanArg,ObjectanotherArg,StringyetAnotherArg,
ObjectandStillAnother）{
...
}
//比上一行缩进一级原则
privatestaticsynchronizedhorkingLongMethodName（intanArg,
ObjectanotherArg,StringyetAnotherArg,
ObjectandStillAnother）{
简单地缩进一级
在使用以上原则时，如果出现太深的缩进，如括号开始处可能在行末附近，这时，只是简单地在上一行的开始处缩进一级。
注释
Java注释语句类型
Java有三种注释语句风格：
以/**开始，*/结束的文档注释，以/*开始，以*/结束的C语言风格注释，以及以//开始，代码行末尾结束的单行注释。
下表是对各类注释语句建议用法的一个概括，也给出了几个例子。
注释语句类型
用法
示例
在接口、类、方法和字段声明之前紧靠它们的位置用文档注释进行说明。
文档注释由javadoc处理，为一个类生成外部注释文档，如下所示。
/**
Customer（顾客）顾客是指作为我们的服务及产品的销售对象的任何个人或组织。
@authorS.W.Ambler
*/
C语言风格注释
采用C语言风格的注释语句将无用的代码注释掉。
保留这些代码是因为用户可能改变想法，或者只是想在调试中暂时不执行这些代码。
/*
这部分代码已被它前面的代码替代，所以于1999年6月4日被B.Gustafsson注释掉。
如果两年之后仍未用这些代码，将其删除。
...（源代码）
单行注释
在方法内部采用单行注释语句对业务逻辑、代码片段和临时变量声明进行说明。
//因为让利活动
//从1995年2月开始，
//所以给所有超过$1000的
//发货单5%的折扣。
快速浏览javadoc
Sun公司的JavaDevelopmentKit（JDK）中有一个名为javadoc的程序。
它可以处理Java的源代码文件，并且为Java程序产生HTML文件形式的外部注释文档。
Javadoc支持一定数目的标记，标识注释文档中各段起始位置的保留字。
详情请参考JDKjavadoc文档。
本规范支持并且要求有Javadoc的注释标记，该标记可由工具自动生成也可由手工制作。
标记
用于
@authorname
类、
接口
说明特定某一段程序代码的作者。
每一个作者各有一个标记。
@deprecated
方法
说明该类的应用程序编程接口（API）已被废弃，因此应不再使用。
@exceptionnamedescription
说明由方法发出的异常。
一个异常采用一个标记，并要给出异常的完整类名。
@paramnamedescription
用来说明传递给一个方法的参数，其中包括参数的类型/类和用法。
每个参数各有一个标记。
@returndescription
若方法有返回值，对该返回值进行说明。
应说明返回值的类型/类和可能的用途。
@since
类、方法
说明自从有JDK1.1以来，该项已存在了多长时间。
@seeClassName
类、接口、方法、字段
在文档中生成指向特定类的超文本链接。
可以并且应该采用完全合法的类名。
@seeClassName#memberfunctionName
在文档中生成指向特定方法的超文本链接。
@versiontext
类、接口
说明特定一段代码的版本信息。
按目的分的注释类型
注释可按其目的分为外部注释、业务逻辑注释及其它注释。
业务逻辑注释是指在类的方法中用于解释业务逻辑的注释，外部注释是指不在类的方法中，是用于对外解释类或类的接口的注释。
变量注释是指不用于外部注释中，对局部变量或私有类变量等变量的注释。
业务逻辑注释
在代码块（如类的方法，静态方法等）中用于解释业务逻辑的注释称为业务逻辑注释，除特殊情况外，业务逻辑注释一般采用单行注释的方式。
代码数，代码数即语句数，不包括变量定义，与代码行数不同。
代码数可用自动化工具获得。
注释数为针对于语句的注释数。
注释数与注释的行数不同，在两条语句之间的注释，不管行数多少，都算作一个注释。
注释率=注释数/代码数*100%。
每个方法的注释率的下限请参见数据一节，但语句数少于3句的除外。
外部注释
不在代码块中，用于对外解释类或类的接口的注释称为外部注释。
外部注释包括类的内容注释、公共方法及变量注释、保护方法及变量注释、包方法及变量注释。
除非特殊情况，外部注释最好采用内容注释的方式。
外部注释的注释率=内容注释数/定义数*100%。
其中定义数是指公用的类或类的接口的数量。
外部注释的注释率的下限请参见数据一节，如为100%，则每一个公共的、保护的、包的方法和变量都应加一个内容注释。
每一个公共、保护及包方法及变量都可能被其它人用到，因此关于该项的说明必须有。
变量注释
不用于外部注释中，对局部变量或私有类变量等变量的注释称为变量注释。
变量注释的注释率=注释数/变量数*100%。
变量注释的注释率的下限请参见数据一节。
3.源文件内容
每个Java源文件只包含一个公共的类或接口，这是Sun公司的规定。
当该公共类附带有私有类或接口时，可以把它们放在该公共类的同一个文件，但公共类必须出现在它们前面。
源文件由以下三部分组成：
文件头注释部分
包及引入部分
类及接口定义部分
每个Java源文件必须以一个C语言风格的注释开始，该注释包括文件名，版本信息，日期，变更记录及版权声明。
参考格式如下：
/*
*<
源文件名>
*
*Versioninformation
*
*Date
*Copyrightnotice
*/
文件名
记录源文件名（不包括路径）。
版本信息
版本信息可选，但如果有的话，必须与配置系统的版本信息兼容。
变更记录
变更记录包含变更日期、变更人和变更内容。
版权声明
版权声明是必须的，其内容必须包括：
公司
年份
可用如下格式：
Copyright2000-2001Topgroup.AllRightsReserved.
Java源文件的第一条非注释行为package语句，包后加一空行，之后可以是一个或多个import语句，例如：
packagejava.awt;
importjava.awt.peer.CanvasPeer;
类及接口定义部分开始于一个内容注释以说明类及接口的功能、环境、使用方法等说明。
类或接口与类或接口之间用一个空行间隔。
变量定义
变量定义包括类变量定义及局部变量定义。
位置
这两种变量定义都应该在其任用域的一开始处定义，即对于类变量，在类的开始处的大括号之后就对它进行定义，对于方法内的局部变量，在方法定义开始处的大括号之后进行定义。
尽量不要在方法内某一块中定义局部变量。
静态变量在最前，按可见性从高到低排列。
若有静态块，则静态块在其后，其后是非静态的类变量，按可见性从高到低排列，即按公共、保护、包、私有的顺序进行排列，不同可见性的类变量组之间应用一个空行进行分隔。
格式
公共的类变量前必须有一个内容注释说明它。
每个变量定义应该占据一行，并且应该对该变量进行注释，但建议不要进行行尾注释，最好在变量定义之前进行注释。
//indentationlevel
intlevel;
//sizeoftable
intsize;
就好于
intlevel,size;
两个同样可见性的变量定义之间不要有空行。
类型不同的变量不要在同一行中，如：
intfoo,fooarray[];
//避免
尽量在定义处对变量进行初始化
方法定义
两个方法定义之间用一个空行分隔。
方法名与参数引导符圆括号之间不要有空格，
方法顺序为：
构造方法
finalize方法
初始化方法
static方法
公共方法
保护方法
包方法
私有方法
方法定义部分开始于一个内容注释以说明该方法的功能、环境、使用方法等所有重要的有助于理解方法的信息，尽可能在其中加入Javadoc标记，当然，这件事有一部分也可能是由设计人员完成的。
有返回值的必须加@return标记，有参数的必须对每一个参数加@param标记，有错误的必须加@exception标记，尽量加@see标记。
这些信息包含但不仅仅局限于以下内容：
方法说明
方法说明对方法整体进行说明，包括以下内容：
3.1.1.1.1成员函数做什么以及它为什么做这个
通过给一个方法加注释，让别人更加容易判断他们是否可以复用代码。
注释出方法为什
升级会员 