Java程序开发规范.docx

1、Java程序开发规范Java 编程规范注：本规范适用于北京工业大学教育部数字社区工程研究中心进行java开发，还待进一步完善。日期操作版本作者2009-4-3起草文件V1.0赵忠诚Java程序开发规范第1章 绪论1.1 目的: 本规范目的是为了使本组织能以标准、规范、统一的编程风格进行Java代码的开发工作。提高程序的可读性、可修改性和可维护性，方便团队的交流。 本规范参考了: 1.2 范围: 本规范适用于教育部数字社区工程研究中心使用Java开发团队所有成员，进行产品开发、维护以及升级等编程操作。1.3 概要说明: 在这里引用文献1来说明代码规范的重要性: 一个软件的生命周期中，有80%都在

2、进行维护； 很难有软件在整个生命周期中，都是由原来的作者进行维护的； 编码规范提高了软件的可读性，并且帮助软件工程师更加快速彻底地理解新的代码； 要想把你的源代码作为产品来发布，就需要保证它像你创作的其他作品那样被很好地封装，并且清理干净了。 针对我们学校环境来说，师兄师姐毕业，师弟师妹入学属于软件工程师的不断更新，如果我们没有统一的完成的编程规范，每个人按照自己的编程风格和编程方法进行程序开发，在毕业之后很少有人能读懂他的程序，对于后期的维护来说是一件非常头疼的问题，所以我们非常有必要总结出一套适合我们自己的Java开发规范。1.4 重要说明: 本规范为内部共享资源，版权属于教育部数字工程研

3、究中心，如果现在或者以后有好的建议可以直接在该文件中进行添加和修改。第2章 代码整体组织和风格 这里所说的代码的整体组织和风格是针对一个文件而言，一个文件应该是由被空行分隔开的代码块所组成，并且每个块被特定的注释标识出来。每个文件不应该超过2000行(包括注释说明)。2.1 Java源文件 Java源文件必须包含一下几个部分(按照从上到下的顺序说明)：版权说明、包和引用语句、类/接口描述以及版本信息、类方法以及变量声明和实现。 版权信息，所有的源文件都应该由列出了类名，日期和版权信息的C-style的注释开始，采用如下格式作为版权信息:/* * #S.java Created on 2009-

4、4-6 * * CopyRight (c) 2009 BJUT,BeiJing. * All right reserved. */ 包和引用语句, 大多数Java源文件的第一个非注释代码行都是包定义语句,当让可以不写包定义语句，但是在这里强烈建议写上包定义语句(如果你采用eclipse等开发环境写不写就由不得你了，除非你在它自动生成之后将其删掉)，在之后就是引用语句，如果引用的话当然没有引用语句。做如下规定：1) 包信息和引用语句之间要与一个空行2) 引用语句之间不在同一个包中的引用也要有一个空行例如：package edu.bjut.bjwater.checkrules.action;imp

5、ort java.text.NumberFormat;import java.text.SimpleDateFormat;import java.util.*;import javax.servlet.http.HttpServletRequest;import javax.servlet.http.HttpSession;import edu.bjut.bjwater.pub.*; 类/接口描述以及版本信息/* * Package: src.test * Description: TODO(用一句话描述该文件做什么) * author : yan * date : 2009-4-6 * ve

6、rsion: V1.0 * * version date author modify * - - - - * 修改之后版本 修改日期 修改者 修改内容 */ 变量声明，按照文献1中所说，在声明变量时，首先声明static变量然后再声明类成员变量，声明顺序为，首先是public的类变量，然后是protected的,接下来是包级的（没有访问修饰符），最后是private的。例： /* something .*/ public static String str = “test”; /* * Set the character set for the file. */private static C

7、harset charset = Charset.forName(ISO-8859-15); /* something .*/ public String str = “test”; /* * The character buffer reference. */ private CharBuffer indexFile; 变量声明同时也要添加相应注释，注释这个变量的功能，如果是一个较复杂的数据结构形式，将其存贮的格式也表示出来，方便理解程序同时也方便其他人的程序调用。 构造函数和方法:构造函数也是方法但是它没有返回值，本规范规定，想写构造函数在写其他的方法。方法也要加上注释，说明这个方法实现的

8、功能等信息，例如 /* * Title : main * Description : TODO方法功能描述 * param args * author: yan 2009-4-6 * version: * * version date author modify * - - - - * 修改之后版本 修改日期 修改者 修改内容 */ 方法的参数以及返回类型一定要详细填写，参数包括参数要求的类型，以及参数的说明；返回值包括返回的类型以及返回之后的数据结构等信息。 2.2 缩进 缩进使得程序看起来清晰和结构化，本规范规定采用4个空格作为缩进单位。eclipse默认的TAB缩进为4个空格，不同的ID

9、E工具可能不太一样，需要进行设置TAB代表的空格。但是如果程序层次缩进过多的话使得程序易读性差，在遇到这种情况时应将部分子功能提取出来作为单独的方法。2.3 函数体长度 前面已经提到整个文件不应该超过2000行，而作为函数体也有相应的要求，为了方便程序阅读和理解，函数体应该尽量控制在150行左右(只是看到有人这样写，具体多少合适我也不是很清楚)。避免出现大类和大方法，对于程序的维护是相当困难的。所以我们提倡小方法以及方法的重用性操作。2.4 行宽 本规范规定每一行的最长宽度为80字符，因为超过了这个宽度之后有些工具不能很好的处理，就算是能够处理，我们也不要超过这个宽度，这也是程序可读性的一个要

10、求。2.5 换行 换行在编程的时候是避免不了的，所以对于换行文献1中提出了一些基本的要求。 在一个“，”后面断行 在一个操作符前面换行，操作符放在新行之首(确保突出操作符) 在较高级别处换行，不要在较低级别处换行 if表达式尽量使用8个空格换行操作，因为4个空格换行操作使得函数体不容易辨认。 拆分出的新行要适当进行缩进，使得排版整齐，可读性强。例：someMethod(longExpression1, longExpression2, longExpression3, longExpression4, longExpression5);/DONT USE THIS INDENTATIONif

11、(condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) /BAD WRAPS doSomethingAboutIt(); /函数体不容易辨认 /USE THIS INDENTATION INSTEADif (condition1 & condition2) | (condition3 & condition4) |!(condition5 & condition6) doSomethingAboutIt(); longName1 = longName2 * (longName3 + lo

12、ngName4 - longName5) + 4 * longname6; / 推荐longName1 = longName2 * (longName3 + longName4 - longName5) + 4 * longname6; /避免这种换行2.6 空行 适当空行的使用可以提高代码的可读性。规定如下： 在下列情况下使用一个空行 两个方法之间 块注释或者单行注释之前 一个方法的两个逻辑段之间，逻辑上密切的地方不加空行，其他地方应该加上空行分隔/* * Here is a block comment. */if (condition) /* Handle the condition. *

13、/ .while (condition) statement1; / 空行 if (condition) statement2; else statement3; / 空行 statement4;2.7 空格 在下列情况下使用空格：1) 关键字之后要留空格。象const、static、final等关键字之后至少要留一个空格，否则无法辨析关键字。象if、for、while等关键字之后应留一个空格再跟左括号（，以突出关键字。2) 函数名之后不要留空格，紧跟左括号（，以与关键字区别。3) “，”或者“；”后要留空格，如for (initialization; condition; update)、F

14、unction(int x, int y, int z)4) “(”向后跟紧，除了“（”前为关键字情况留空格外，而“）”、“；”向前跟紧，也就是在他们之前没有空格出现；5) 所有的二元操作符号：赋值操作符、比较操作符、算术操作符、逻辑操作符、位域操作符，如“=”、“+=” “=”、“=”、“+”、“*”、“%”、“&”、“|”、“”,“”等二元操作符的前后应当加空格。6) 所有一元操作符前后不加空格，“!”、“+”、“-”前后都不加空格7) 强制转换后应该紧跟一个空格，如myMethod(byte) aNum, (Object) x);第3章 命名规范3.1 基本规则 规范化的命名可以使程序易

15、于阅读和理解，不仅仅方便自己日后看程序方便同时也方便他人进行代码的维护工作。a) 命名是采用完成的英文描述，禁止使用汉语拼音和汉语进行命名。b) 尽量少用缩写形式命名c) 命名中尽量少出现或者不出现数字，当然用2代表to,或者4代表for是可以的。d) 避免使用相似或者仅仅在大小写上区分的名字标识符类型命名规则例子包(package)1、一个唯一包名的前缀总是全部小写的ASCII字母并且是一个顶级域名，通常是com,edu,govnet,org2、edu.bju基本包,所有包和文件都在基本包下3、包名称按照如下规则组成【基本包】.【项目名】.【模块名】.【子模块名】.edu.bjut.bjwa

16、ter类(Classes)采用大小写混合的方式，每个单词的首字母大写，所命名称要能反映出类的功能class Raster;class ImageSprite;接口(Interfaces)与类命名规则一样方法(Methods)采用大小写混合的方式，第一个单词的首字母小写，其后单词的首字母大写。第一个单词常常采用具有具有动作色彩的动词runFast();getBackground();变量(Variables)第一个单词的首字母小写，其后单词的首字母大写；对于不易识别类型的变量加上类型标示(Hashtable keyEleHashtable; List allStudentsList)Boolea

17、n isXXXBoolean hasXXXString strXXX实例变量Instance Variables大小写规则和变量名相似，除了前面需要一个下划线String _name常量(Constants)应该全部大写，单词间用下划线隔开MAX_WIDTH注意：在程序开发过程中避免出现莫名的数字，既然是一个常量，那就给定义为常量来操作，不要出现不知道是什么意思的常量，使得程序变得很神秘。第4章 表达式和基本语句第5章 注释第6章 附录版本信息 一、GNU 风格的版本号命名格式 :主版本号 . 子版本号 . 修正版本号 . 编译版本号 英文对照 : Major_Version_Number.M

18、inor_Version_Number.Revision_Number.Build_Number示例 : 1.2.1, 2.0, 5.0.0 build-13124二、Windows 风格的版本号命名格式 :主版本号 . 子版本号 修正版本号 . 编译版本号 英文对照 : Major_Version_Number.Minor_Version_NumberRevision_Number.Build_Number示例: 1.21, 2.0三、.Net Framework 风格的版本号命名格式:主版本号.子版本号.编译版本号.修正版本号英文对照: Major_Version_Number.Minor

19、_Version_Number.Build_Number.Revision_Number版本号由二至四个部分组成：主版本号、次版本号、内部版本号和修订号。主版本号和次版本号是必选的；内部版本号和修订号是可选的，但是如果定义了修订号部分，则内部版本号就是必选的。所有定义的部分都必须是大于或等于 0 的整数。应根据下面的约定使用这些部分：Major ：具有相同名称但不同主版本号的程序集不可互换。例如，这适用于对产品的大量重写，这些重写使得无法实现向后兼容性。Minor ：如果两个程序集的名称和主版本号相同，而次版本号不同，这指示显著增强，但照顾到了向后兼容性。例如，这适用于产品的修正版或完全向后兼

20、容的新版本。Build ：内部版本号的不同表示对相同源所作的重新编译。这适合于更改处理器、平台或编译器的情况。Revision ：名称、主版本号和次版本号都相同但修订号不同的程序集应是完全可互换的。这适用于修复以前发布的程序集中的安全漏洞。程序集的只有内部版本号或修订号不同的后续版本被认为是先前版本的修补程序 (Hotfix) 更新。版本号管理策略一、 GNU 风格的版本号管理策略：1项目初版本时 , 版本号可以为 0.1 或 0.1.0, 也可以为 1.0 或 1.0.0, 如果你为人很低调 , 我想你会选择那个主版本号为 0 的方式 ;2当项目在进行了局部修改或 bug 修正时 , 主版本

21、号和子版本号都不变 , 修正版本号加 1;3. 当项目在原有的基础上增加了部分功能时 , 主版本号不变 , 子版本号加 1, 修正版本号复位为 0, 因而可以被忽略掉 ;4当项目在进行了重大修改或局部修正累积较多 , 而导致项目整体发生全局变化时 , 主版本号加 1;5另外 , 编译版本号一般是编译器在编译过程中自动生成的 , 我们只定义其格式 , 并不进行人为控制 .二、 Window 下的版本号管理策略：1目初版时 , 版本号为 1.0 或 1.00;2. 当项目在进行了局部修改或 bug 修正时，主版本号和子版本号都不变 , 修正版本号加 1;3. 当项目在原有的基础上增加了部分功能时

22、, 主版本号不变 , 子版本号加 1, 修正版本号复位为 0, 因而可以被忽略掉 ;4. 当项目在进行了重大修改或局部修正累积较多 , 而导致项目整体发生全局变化时 , 主版本号加 1;5. 另外 , 编译版本号一般是编译器在编译过程中自动生成的 , 我们只定义其格式 , 并不进行人为控制 .另外 , 还可以在版本号后面加入 Alpha, Beta, Gamma, Current, RC (Release Candidate), Release, Stable 等后缀 , 在这后缀后面还可以加入 1 位数字的版本号 .对于用户来说 , 如果某个软件的主版本号进行了升级 , 用户还想继续那个软件

23、 , 则发行软件的公司一般要对用户收取升级费用 ; 而如果子版本号或修正版本号发生了升级 , 一般来说是免费的 .附： alphal 内部测试版 beta 外部测试版 demo 演示版 Enhance 增强版或者加强版 属于正式版 Free 自由版 Full version 完全版 属于正式版 shareware 共享版 Release 发行版 有时间限制 Upgrade 升级版 Retail 零售版 Cardware 属共享软件的一种，只要给作者回复一封电邮或明信片即可。（有的作者并由此提供注册码等），目前这种形式已不多见。 Plus 属增强版，不过这种大部分是在程序界面及多媒体功能上增强。

24、 Preview 预览版 Corporation & Enterprise 企业版 Standard 标准版 Mini 迷你版也叫精简版只有最基本的功能 Premium 贵价版 Professional 专业版 Express 特别版 Deluxe 豪华版 Regged 已注册版 CN 简体中文版 CHT 繁体中文版 EN 英文版 Multilanguage 多语言版注释：版此版本表示该软件仅仅是一个初步完成品，通常只在软件开发者内部交流，也有很少一部分发布给专业测试人员。一般而言，该版本软件的 bug 较多，普通用户最好不要安装。（beta）版该版本相对于版已有了很大的改进，消除了严重的错误

25、，但还是存在着一些缺陷，需要经过大规模的发布测试来进一步消除。这一版本通常由软件公司免费发 布，用户可从相关的站点下载。通过一些专业爱好者的测试，将结果反馈给开发者，开发者们再进行有针对性的修改。该版本也不适合一般用户安装。版该版本已经相当成熟了，与即将发行的正式版相差无几，如果用户实在等不及了，尽可以装上一试。trial（试用版）试用版软件在最近的几年里颇为流行，主要是得益于互联网的迅速发展。该版本软件通常都有时间限制，过期之后用户如果希望继续使用，一般得交纳一定的费用进行注册或购买。有些试用版软件还在功能上做了一定的限制。unregistered（未注册版）未注册版与试用版极其类似，只是未

26、注册版通常没有时间限制，在功能上相对于正式版做了一定的限制，例如绝大多数网络电话软件的注册版和未注册版，两者 之间在通话质量上有很大差距。还有些虽然在使用上与正式版毫无二致，但是动不动就会弹出一个恼人的消息框来提醒你注册，如看图软件 acdsee 、智能陈桥汉字输入软件等。demo版也称为演示版，在非正式版软件中，该版本的知名度最大。 demo 版仅仅集成了正式版中的几个功能，颇有点像 unregistered 。不同的是， demo 版一般不能通过升级或注册的方法变为正式版。以上是软件正式版本推出之前的几个版本，、可以称为测试版，大凡成熟软件总会有多个测试版，如 windows 98 的版，

27、前前后后将近有 10 个。这么多的测试版一方面为了最终产品尽可能地满足用户的需要，另一方面也尽量减少了软件中的 bug 。而 trial 、 unregistered 、 demo 有时统称为演示版，这一类版本的广告色彩较浓，颇有点先尝后买的味道，对于普通用户而言自然是可以免费尝鲜了。正式版不同类型的软件的正式版本通常也有区别。release该版本意味“最终释放版”，在出了一系列的测试版之后，终归会有一个正式版本，对于用户而言，购买该版本的软件绝对不会错。该版本有时也称为标准版。 一般情况下， release 不会以单词形式出现在软件封面上，取而代之的是符号 (r) ，如 windows nt

28、(r) 4.0 、 ms-dos(r) 6.22 等。registered很显然，该版本是与 unregistered 相对的注册版。注册版、 release 和下面所讲的 standard 版一样，都是软件的正式版本，只是注册版软件的前身有很大一部分是从网上下载的。standard这是最常见的标准版，不论是什么软件，标准版一定存在。标准版中包含了该软件的基本组件及一些常用功能，可以满足一般用户的需求。其价格相对高一级版本而言还是“平易近人”的。deluxe顾名思义即为“豪华版”。豪华版通常是相对于标准版而言的，主要区别是多了几项功能，价格当然会高出一大块，不推荐一般用户购买。此版本通常是为那

29、些追求“完美”的专业用户所准备的。reference该版本型号常见于百科全书中，比较有名的是微软的 encarta 系列。 reference 是最高级别，其包含的主题、图像、影片剪辑等相对于 standard 和 deluxe 版均有大幅增加，容量由一张光盘猛增至三张光盘，并且加入了很强的交互功能，当然价格也不菲。可以这么说，这一版本的百科全书才能算是真正的百科全书，也 是发烧友们收藏的首选。professional（专业版）专业版是针对某些特定的开发工具软件而言的。专业版中有许多内容是标准版中所没有的，这些内容对于一个专业的软件开发人员来说是极为重要的。如微软的 visual foxpro 标准版并不具备编译成可执行文件的功能，这对于一个完整的开发项目而言显然是无法忍受的，若客户机上没有 foxpro 将不能使用。如果用专业版就没有这个问题了。enterprise（企业版）企业版是开发类软件中的极品（相当于百科全书中的 reference 版）。拥有一套这种版本的软件可以毫无障碍地开发任何级别的应用软件。如著名的 visual c+ 的企业版相对于专业版来说增加了几个附加的特性，如 sql 调试、扩展的存储过程向导、支持 as/400 对 ole db 的访问等。而这一版本的价格也是普通用户无法接受的。如微软的 vis