Java程序开发规范Word文档格式.docx

Java程序开发规范Word文档格式.docx

《Java程序开发规范Word文档格式.docx》由会员分享，可在线阅读，更多相关《Java程序开发规范Word文档格式.docx（13页珍藏版）》请在冰豆网上搜索。

这里所说的代码的整体组织和风格是针对一个文件而言，一个文件应该是由被空行分隔开的代码块所组成，并且每个块被特定的注释标识出来。

每个文件不应该超过2000行（包括注释说明）。

2.1Java源文件

Java源文件必须包含一下几个部分（按照从上到下的顺序说明）：

版权说明、包和引用语句、类/接口描述以及版本信息、类方法以及变量声明和实现。

版权信息，所有的源文件都应该由列出了类名，日期和版权信息的C-style的注释开始，采用如下格式作为版权信息:

/**

*@{#}S.javaCreatedon2009-4-6

*

*CopyRight（c）2009BJUT,BeiJing.

*Allrightreserved.

*/

包和引用语句,大多数Java源文件的第一个非注释代码行都是包定义语句,当让可以不写包定义语句，但是在这里强烈建议写上包定义语句（如果你采用eclipse等开发环境写不写就由不得你了，除非你在它自动生成之后将其删掉），在之后就是引用语句，如果引用的话当然没有引用语句。

做如下规定：

1）包信息和引用语句之间要与一个空行

2）引用语句之间不在同一个包中的引用也要有一个空行

例如：

packageedu.bjut.bjwater.checkrules.action;

importjava.text.NumberFormat;

importjava.text.SimpleDateFormat;

importjava.util.*;

importjavax.servlet.http.HttpServletRequest;

importjavax.servlet.http.HttpSession;

importedu.bjut.bjwater.pub.*;

类/接口描述以及版本信息

*@Package:

src.test

*@Description:

TODO（用一句话描述该文件做什么）

*@author:

yan

*@date:

2009-4-6

*@version:

V1.0

*@version@date@author@modify

*------------------------------------------------

*修改之后版本修改日期修改者修改内容

变量声明，按照文献1中所说，在声明变量时，首先声明static变量然后再声明类成员变量，声明顺序为，首先是public的类变量，然后是protected的,接下来是包级的（没有访问修饰符），最后是private的。

例：

/**something......*/

publicstaticStringstr=“test”;

…………………

/**

*Setthecharactersetforthefile.

privatestaticCharsetcharset=Charset.forName（"

ISO-8859-15"

）;

publicStringstr=“test”;

*Thecharacterbufferreference.

privateCharBufferindexFile;

变量声明同时也要添加相应注释，注释这个变量的功能，如果是一个较复杂的数据结构形式，将其存贮的格式也表示出来，方便理解程序同时也方便其他人的程序调用。

构造函数和方法:

构造函数也是方法但是它没有返回值，本规范规定，想写构造函数在写其他的方法。

方法也要加上注释，说明这个方法实现的功能等信息，例如

*@Title:

main

*@Description:

TODO方法功能描述

*@paramargs

*@author:

yan2009-4-6

*

方法的参数以及返回类型一定要详细填写，参数包括参数要求的类型，以及参数的说明；

返回值包括返回的类型以及返回之后的数据结构等信息。

2.2缩进

缩进使得程序看起来清晰和结构化，本规范规定采用4个空格作为缩进单位。

eclipse默认的TAB缩进为4个空格，不同的IDE工具可能不太一样，需要进行设置TAB代表的空格。

但是如果程序层次缩进过多的话使得程序易读性差，在遇到这种情况时应将部分子功能提取出来作为单独的方法。

2.3函数体长度

前面已经提到整个文件不应该超过2000行，而作为函数体也有相应的要求，为了方便程序阅读和理解，函数体应该尽量控制在150行左右（只是看到有人这样写，具体多少合适我也不是很清楚）。

避免出现大类和大方法，对于程序的维护是相当困难的。

所以我们提倡小方法以及方法的重用性操作。

2.4行宽

本规范规定每一行的最长宽度为80字符，因为超过了这个宽度之后有些工具不能很好的处理，就算是能够处理，我们也不要超过这个宽度，这也是程序可读性的一个要求。

2.5换行

换行在编程的时候是避免不了的，所以对于换行文献1中提出了一些基本的要求。

在一个“，”后面断行

在一个操作符前面换行，操作符放在新行之首（确保突出操作符）

在较高级别处换行，不要在较低级别处换行

if表达式尽量使用8个空格换行操作，因为4个空格换行操作使得函数体不容易辨认。

拆分出的新行要适当进行缩进，使得排版整齐，可读性强。

someMethod（longExpression1,longExpression2,longExpression3,

longExpression4,longExpression5）;

//DON'

TUSETHISINDENTATION

if（（condition1&

&

condition2）

||（condition3&

condition4）

||!

（condition5&

condition6））{//BADWRAPS

doSomethingAboutIt（）;

//函数体不容易辨认

}

//USETHISINDENTATIONINSTEAD

condition6））{

longName1=longName2*（longName3+longName4-longName5）

+4*longname6;

//推荐

longName1=longName2*（longName3+longName4

-longName5）+4*longname6;

//避免这种换行

2.6空行

适当空行的使用可以提高代码的可读性。

规定如下：

在下列情况下使用一个空行

两个方法之间

块注释或者单行注释之前

一个方法的两个逻辑段之间，逻辑上密切的地方不加空行，其他地方应该加上空行分隔

/*

*Hereisablockcomment.

if（condition）{

/*Handlethecondition.*/

...

}

while（condition）{

statement1;

//空行

if（condition）{

statement2;

}else{

statement3;

}

//空行

statement4;

2.7空格

在下列情况下使用空格：

1）关键字之后要留空格。

象const、static、final等关键字之后至少要留一个空格，否则无法辨析关键字。

象if、for、while等关键字之后应留一个空格再跟左括号‘（’，以突出关键字。

2）函数名之后不要留空格，紧跟左括号‘（’，以与关键字区别。

3）“，”或者“；

”后要留空格，如for（initialization;

condition;

update）、Function（intx,inty,intz）

4）“（”向后跟紧，除了“（”前为关键字情况留空格外，而“）”、“；

”向前跟紧，也就是在他们之前没有空格出现；

5）所有的二元操作符号：

赋值操作符、比较操作符、算术操作符、逻辑操作符、位域操作符，如“=”、“+=”“>

=”、“<

=”、“+”、“*”、“%”、“&

”、“||”、“<

”,“^”等二元操作符的前后应当加空格。

6）所有一元操作符前后不加空格，“!

”、“++”、“--”前后都不加空格

7）强制转换后应该紧跟一个空格，如myMethod（（byte）aNum,（Object）x）;

第3章

命名规范

3.1基本规则

规范化的命名可以使程序易于阅读和理解，不仅仅方便自己日后看程序方便同时也方便他人进行代码的维护工作。

a）命名是采用完成的英文描述，禁止使用汉语拼音和汉语进行命名。

b）尽量少用缩写形式命名

c）命名中尽量少出现或者不出现数字，当然用2代表to,或者4代表for是可以的。

d）避免使用相似或者仅仅在大小写上区分的名字

标识符类型

命名规则

例子

包（package）

1、一个唯一包名的前缀总是全部小写的ASCII字母并且是一个顶级域名，通常是com,edu,govnet,org

2、edu.bju基本包,所有包和文件都在基本包下

3、包名称按照如下规则组成

【基本包】.【项目名】.【模块名】.【子模块名】..

edu.bjut.bjwater

类（Classes）

采用大小写混合的方式，每个单词的首字母大写，所命名称要能反映出类的功能

classRaster;

classImageSprite;

接口（Interfaces）

与类命名规则一样

方法（Methods）

采用大小写混合的方式，第一个单词的首字母小写，其后单词的首字母大写。

第一个单词常常采用具有具有动作色彩的动词

runFast（）;

getBackground（）;

变量（Variables）

第一个单词的首字母小写，其后单词的首字母大写；

对于不易识别类型的变量加上类型标示（HashtablekeyEleHashtable;

ListallStudentsList）

BooleanisXXX

BooleanhasXXX

StringstrXXX

实例变量

InstanceVariables

大小写规则和变量名相似，除了前面需要一个下划线

String_name

常量（Constants）

应该全部大写，单词间用下划线隔开

MAX_WIDTH

注意：

在程序开发过程中避免出现莫名的数字，既然是一个常量，那就给定义为常量来操作，不要出现不知道是什么意思的常量，使得程序变得很神秘。

第4章表达式和基本语句

第5章注释

第6章附录—版本信息

一、GNU风格的版本号命名格式:

主版本号.子版本号[.修正版本号[.编译版本号]]

英文对照:

Major_Version_Number.Minor_Version_Number[.Revision_Number[.Build_Number]]

示例:

1.2.1,2.0,5.0.0build-13124

二、Windows风格的版本号命名格式:

主版本号.子版本号[修正版本号[.编译版本号]]

Major_Version_Number.Minor_Version_Number[Revision_Number[.Build_Number]]

示例:

1.21,2.0

三、.NetFramework风格的版本号命名格式:

主版本号.子版本号[.编译版本号[.修正版本号]]

英文对照:

Major_Version_Number.Minor_Version_Number[.Build_Number[.Revision_Number]]

版本号由二至四个部分组成：

主版本号、次版本号、内部版本号和修订号。

主版本号和次版本号是必选的；

内部版本号和修订号是可选的，但是如果定义了修订号部分，则内部版本号就是必选的。

所有定义的部分都必须是大于或等于0的整数。

应根据下面的约定使用这些部分：

Major：

具有相同名称但不同主版本号的程序集不可互换。

例如，这适用于对产品的大量重写，这些重写使得无法实现向后兼容性。

Minor：

如果两个程序集的名称和主版本号相同，而次版本号不同，这指示显著增强，但照顾到了向后兼容性。

例如，这适用于产品的修正版或完全向后兼容的新版本。

Build：

内部版本号的不同表示对相同源所作的重新编译。

这适合于更改处理器、平台或编译器的情况。

Revision：

名称、主版本号和次版本号都相同但修订号不同的程序集应是完全可互换的。

这适用于修复以前发布的程序集中的安全漏洞。

程序集的只有内部版本号或修订号不同的后续版本被认为是先前版本的修补程序（Hotfix）更新。

版本号管理策略

一、GNU风格的版本号管理策略：

1．项目初版本时,版本号可以为0.1或0.1.0,也可以为1.0或1.0.0,如果你为人很低调,我想你会选择那个主版本号为0的方式;

2．当项目在进行了局部修改或bug修正时,主版本号和子版本号都不变,修正版本号加1;

3.当项目在原有的基础上增加了部分功能时,主版本号不变,子版本号加1,修正版本号复位为0,因而可以被忽略掉;

4．当项目在进行了重大修改或局部修正累积较多,而导致项目整体发生全局变化时,主版本号加1;

5．另外,编译版本号一般是编译器在编译过程中自动生成的,我们只定义其格式,并不进行人为控制.

二、Window下的版本号管理策略：

1．目初版时,版本号为1.0或1.00;

2.当项目在进行了局部修改或bug修正时，主版本号和子版本号都不变,修正版本号加1;

4.当项目在进行了重大修改或局部修正累积较多,而导致项目整体发生全局变化时,主版本号加1;

5.另外,编译版本号一般是编译器在编译过程中自动生成的,我们只定义其格式,并不进行人为控制.

　　另外,还可以在版本号后面加入Alpha,Beta,Gamma,Current,RC（ReleaseCandidate）,Release,Stable等后缀,在这后缀后面还可以加入1位数字的版本号.

　　对于用户来说,如果某个软件的主版本号进行了升级,用户还想继续那个软件,则发行软件的公司一般要对用户收取升级费用;

而如果子版本号或修正版本号发生了升级,一般来说是免费的.

附：

alphal内部测试版

　　beta外部测试版

　　demo演示版

　　Enhance增强版或者加强版属于正式版

　　Free自由版

　　Fullversion完全版属于正式版

　　shareware共享版

　　Release发行版有时间限制

　　Upgrade升级版

　　Retail零售版

　　Cardware属共享软件的一种，只要给作者回复一封电邮或明信片即可。

（有的作者并由此提供注册码等），目前这种形式已不多见。

　　Plus属增强版，不过这种大部分是在程序界面及多媒体功能上增强。

　　Preview预览版

　　Corporation&

Enterprise企业版

　　Standard标准版

　　Mini迷你版也叫精简版只有最基本的功能

　　Premium—贵价版

　　Professional—专业版

　　Express—特别版

　　Deluxe—豪华版

　　Regged—已注册版

　　CN—简体中文版

　　CHT—繁体中文版

　　EN—英文版

　　Multilanguage—多语言版

注释：

α版

　　此版本表示该软件仅仅是一个初步完成品，通常只在软件开发者内部交流，也有很少一部分发布给专业测试人员。

一般而言，该版本软件的bug较多，普通用户最好不要安装。

β（beta）版

　　该版本相对于α版已有了很大的改进，消除了严重的错误，但还是存在着一些缺陷，需要经过大规模的发布测试来进一步消除。

这一版本通常由软件公司免费发布，用户可从相关的站点下载。

通过一些专业爱好者的测试，将结果反馈给开发者，开发者们再进行有针对性的修改。

该版本也不适合一般用户安装。

γ版

　　该版本已经相当成熟了，与即将发行的正式版相差无几，如果用户实在等不及了，尽可以装上一试。

trial（试用版）

　　试用版软件在最近的几年里颇为流行，主要是得益于互联网的迅速发展。

该版本软件通常都有时间限制，过期之后用户如果希望继续使用，一般得交纳一定的费用进行注册或购买。

有些试用版软件还在功能上做了一定的限制。

unregistered（未注册版）

　　未注册版与试用版极其类似，只是未注册版通常没有时间限制，在功能上相对于正式版做了一定的限制，例如绝大多数网络电话软件的注册版和未注册版，两者之间在通话质量上有很大差距。

还有些虽然在使用上与正式版毫无二致，但是动不动就会弹出一个恼人的消息框来提醒你注册，如看图软件acdsee、智能陈桥汉字输入软件等。

demo版

　　也称为演示版，在非正式版软件中，该版本的知名度最大。

demo版仅仅集成了正式版中的几个功能，颇有点像unregistered。

不同的是，demo版一般不能通过升级或注册的方法变为正式版。

　　以上是软件正式版本推出之前的几个版本，α、β、γ可以称为测试版，大凡成熟软件总会有多个测试版，如windows98的β版，前前后后将近有10个。

这么多的测试版一方面为了最终产品尽可能地满足用户的需要，另一方面也尽量减少了软件中的bug。

而trial、unregistered、demo有时统称为演示版，这一类版本的广告色彩较浓，颇有点先尝后买的味道，对于普通用户而言自然是可以免费尝鲜了。

正式版　不同类型的软件的正式版本通常也有区别。

release

　　该版本意味“最终释放版”，在出了一系列的测试版之后，终归会有一个正式版本，对于用户而言，购买该版本的软件绝对不会错。

该版本有时也称为标准版。

一般情况下，release不会以单词形式出现在软件封面上，取而代之的是符号（r），如windowsnt（r）4.0、ms-dos（r）6.22等。

registered

　　很显然，该版本是与unregistered相对的注册版。

注册版、release和下面所讲的standard版一样，都是软件的正式版本，只是注册版软件的前身有很大一部分是从网上下载的。

standard

　　这是最常见的标准版，不论是什么软件，标准版一定存在。

标准版中包含了该软件的基本组件及一些常用功能，可以满足一般用户的需求。

其价格相对高一级版本而言还是“平易近人”的。

deluxe

　　顾名思义即为“豪华版”。

豪华版通常是相对于标准版而言的，主要区别是多了几项功能，价格当然会高出一大块，不推荐一般用户购买。

此版本通常是为那些追求“完美”的专业用户所准备的。

reference

　　该版本型号常见于百科全书中，比较有名的是微软的encarta系列。

reference是最高级别，其包含的主题、图像、影片剪辑等相对于standard和deluxe版均有大幅增加，容量由一张光盘猛增至三张光盘，并且加入了很强的交互功能，当然价格也不菲。

可以这么说，这一版本的百科全书才能算是真正的百科全书，也是发烧友们收藏的首选。

professional（专业版）

　　专业版是针对某些特定的开发工具软件而言的。

专业版中有许多内容是标准版中所没有的，这些内容对于一个专业的软件开发人员来说是极为重要的。

如微软的visualfoxpro标准版并不具备编译成可执行文件的功能，这对于一个完整的开发项目而言显然是无法忍受的，若客户机上没有foxpro将不能使用。

如果用专业版就没有这个问题了。

enterprise（企业版）

　　企业版是开发类软件中的极品（相当于百科全书中的reference版）。

拥有一套这种版本的软件可以毫无障碍地开发任何级别的应用软件。

如著名的visualc++的企业版相对于专业版来说增加了几个附加的特性，如sql调试、扩展的存储过程向导、支持as/400对oledb的访问等。

而这一版本的价格也是普通用户无法接受的。

如微软的vis