Java开发规范

文档名称Java开发规范版本2.0alpha文档编号日期2010-11-25Java开发规范第1章绪论1.1目的本规范的目的是使本组织能以标准的、规范的方式设计和编码。通过建立编码规范，以使每个开发人员养成良好的编码风格和习惯；并以此形成开发小组编码约定，提高程序的可靠性、可读性、可修改性、可维护性和一致性等，增进团队间的交流，并保证软件产品的质量。1.2范围本规范适用于“SkyinnGroup”及其下所有软件项目、产品等的设计、开发以及维护、升级等。本规范使用于“SkyinnGroup”的所有软件开发人员，在整个软件开发过程中必须遵循此规范。1.3版权声明本文档为共享文档，不限转载，但请保持本文档的完整性。您可以修改本文档以符合您或组织、公司等之实际，但请在文档中保持对本文档的引用和说明。未经本人授权，任何个人、组织或单位不得将本文档用于书面发表、转载、摘录等，亦不得用于其他商业行为。本人及本组织不承担任何因使用、参考本文档等而导致的任何可能责任或连带责任。1.4参考资料《Java编程指南》见RUP（RationalUnifiedProcess）中文版。《Java技术手册》(JavainaNutshell)《SunJava语言编码规范》(JavaCodeConventions)《EffictiveJava》《JavaPitfalls》《JavaRules》1.5概述对于代码，首要要求是它必须正确，能够按照设计预定功能去运行；第二是要求代码必须清晰易懂，使自己和其他的程序员能够很容易地理解代码所执行的功能等。然而，在实际开发中，每个程序员所写的代码却经常自成一套，很少统一，导致理解困难，影响团队的开发效率及系统的质量等。因此，一份完整并被严格执行的开发规范是非常必须的，特别是对软件公司的开发团队而言。此规范参考自业界标准编程规范并结合本人多年编程经验、习惯等而制定，在本人工作过的公司中都曾参考本文档而形成内部开发规范并执行。现在将本文档共享之，希望能对各位有所帮助，并做引玉之砖，希望各位朋友将自己的经验等增补进去，对我们所热爱的软件业有所裨益。最根本的原则：代码虽然是给机器运行的，但却是给人读的！运用常识。当找不到任何规则或指导方针，当规则明显不能适用，当所有的方法都失效的时共享第5页/共5页文档名称Java开发规范版本文档编号日期2004-7-18侯：运用常识并核实这些基本原则。这条规则比其它所有规则都重要。常识是必不可少。当出现该情况时，应当及时收集并提交，以便对本规范进行修改。共享第6页/共6页第2章代码组织与风格2.1基本原则代码的组织和风格的基本原则是：便于自己的开发，易于与他人的交流。因个人习惯和编辑器等可以设置和形成自己的风格，但必须前后一致，并符合本规范的基本要求和原则。本章所涉及到的内容一般都可在Java集成编辑环境中进行相应设置，也可由Ant等调用checkstyle等来进行自动规整。开发工具经项目负责人调试后统一确定。开发工具一经确定不允许集成任何非统一插件，若有需要，经项目负责人同意后统一为项目组成员添加。开发工具的编码格式不允许修改。2.2缩进子功能块当在其父功能块后缩进。当功能块过多而导致缩进过深时当将子功能块提取出来做为子函数。代码中以TAB（4个字符）缩进，在编辑器中请将TAB设置为以空格替代，否则在不同编辑器或设置下会导致TAB长度不等而影响整个程序代码的格式。例如：Table1．缩进示例publicvoidmethodName(){if(somecondition){for(…){//somesentences}//endfor}//endif}2.3长度为便于阅读和理解，单个函数的有效代码长度当尽量控制在80行以内（不包括注释行），当一个功能模块过大时往往造成阅读困难，因此当使用子函数等将相应功能抽取出来，这也有利于提高代码的重用度。单个类也不宜过大，当出现此类情况时当将相应功能的代码重构到其他类中，通过组合等方式来调用，建议单个类的长度包括注释行不超过1500行。尽量避免使用大类和长方法。2.4行宽页宽应该设置为80字符。一般不要超过这个宽度,这会导致在某些机器中无法以一屏来完整显示,但这一设置也可以灵活调整。在任何情况下,超长的语句应该在一个逗号后或一个操作符前折行。一条语句折行后,应该比原来的语句再缩进一个TAB或4个空格，以便于阅读。2.5间隔类、方法及功能块间等应以空行相隔，以增加可读性，但不得有无规则的大片空行。操作符两端应当各空一个字符以增加可读性。相应独立的功能模块之间可使用注释行间隔，并标明相应内容，具体参看附录的代码示例2.6对齐关系密切的行应对齐，对齐包括类型、修饰、名称、参数等各部分对齐。连续赋值时当对齐操作符。共享文档名称Java开发规范版本文档编号日期2010-11-25第7页/共7页文档名称Java开发规范版本文档编号日期2010-11-25当方法参数过多时当在每个参数后（逗号后）换行并对齐。当控制或循环中的条件比较长时当换行（操作符前）、对齐并注释各条件。变量定义最好通过添加空格形成对齐，同一类型的变量应放在一起。如下例所示：Table2．对齐示例//变量对齐-----------------------------------------------intcount=100;intlength=0;StringstrUserName=null;Integer[]porductCode=newInteger(2);//产品编码数组//参数对齐----------------------------------------------publicConnectiongetConnection(Stringurl,StringuserName,Stringpassword)throwsSQLException,IOException{}//换行对齐----------------------------------------------publicfinalstaticStringSQL_SELECT_PRODUCT=“SELECT*“+“FROMTProductWHEREProd_ID=”+prodID;//条件对齐----------------------------------------------if(Condition1&&Condition2//当条件一//并且条件二||Condition3){//或者条件三}for(inti=0;iproductCount.length;//循环终止条件i++){}2.7括号{}中的语句应该单独作为一行，左括号{当紧跟其语句后，右括号}永远单独作为一行且与其匹配行对齐，并尽量在其后说明其匹配的功能模块。较长的方法以及类、接口等的右括号后应使用//end...等标识其结束。如:类的结束符：}//EOCClassName，方法结束符：}//endmethodName()，功能块结束：}//endif...userNameisnull?循环快结束：}//endfor...everyuserinuserList不要在程序中出现不必要的括号，但有时为了增加可读性和便于理解，当用括号限定相应项。左括号是否换行等随个人习惯而定，若换行则当与其前导语句首字符对齐。共享第8页/共8页文档名称Java开发规范版本文档编号日期2010-11-25第3章注释3.1基本原则3.1.13.1.23.1.33.1.43.1.53.1.63.1.7注释应该增加代码的清晰度。代码注释的目的是要使代码更易于被其他开发人员等理解。如果你的程序不值得注释，那么它很可能也不值得运行。避免使用装饰性内容。保持注释的简洁。注释信息不仅要包括代码的功能，还应给出原因。不要为注释而注释。除变量定义等较短语句的注释可用行尾注释外，其他注释当避免使用行尾注释。3.2JavaDoc对类、方法、变量等的注释需要符合JavaDoc规范，对每个类、方法都应详细说明其功能、条件、参数等，并使用良好的HTML标记格式化注释，以使生成的JavaDoc易阅读和理解。。3.3文件与包注释在每个文件、包的头部都应该包含该文件的功能、作用、作者、版权以及创建、修改记录等。并在其中使用CVS标记自动跟踪版本变化及修改记录等信息。注意是/**/注释而不是/***/JavaDoc注释。文件注释模板见附件《注释模板》中的文件注释部分。版权声明部分请参见附件《版权声明》并注意更新到最新版本。Table3文件注释示例：/***$Id:User.java,v1.12002/09/0714:36:23l_walkerExp$*Created:[2003-3-2320:18:53]byl_walker**ProjectName**Description**CopyrightInformation.*/每个包当有包注释，在源码及JavaDoc相应包路径下建立package.html以描述包的功能、作用等。共享第9页/共9页文档名称Java开发规范版本文档编号日期2010-11-253.4类、接口注释在类、接口定义之前当对其进行注释，包括类、接口的目的、作用、功能、继承于何种父类，实现的接口、实现的算法、使用方法、示例程序等，在作者和版本域中使用CVS标记自动跟踪版本变化等，具体参看附件《注释模板》中相关部分。Table4类注释示例/***p字符串实用类。/p**定义字符串操作时所需要用到的方法，如转换中文、HTML标记处理等。**@author$Author:l_walker$*@version$Revision:1.2$$Date:2003/05/1502:10:27$*/publicclassStringUtil{…}3.5方法注释依据标准JavaDoc规范对方法进行注释，以明确该方法功能、作用、各参数含义以及返回值等。复杂的算法用/**/在方法内注解出。参数注释时当注明其取值范围等返回值当注释出失败、错误、异常时的返回情况。异常当注释出什么情况、什么时候、什么条件下会引发什么样的异常Table5方法注释示例/***执行查询。**该方法调用Statement的executeQuery(sql)方法并返回ResultSet*结果集。**@paramsql标准的SQL语句*@returnResultSet结果集，若查询失败则返回null*@throwsSQLException当查询数据库时可能引发此异常*/publicResultSetexecuteQuery(Stringsql)throwsSQLException{//Statement和SQL语句都不能为空if(null!=stmt&&!StringUtil.isEmpty(sql)){//返回查询执行结果returnstmt.executeQuery(sql);}returnnull;}//endexecuteQuery()共享第10页/共10页项目注释内容参数参数类型参数用来做什么约束或前提条件示例字段/属性字段描述注释所有使用的不变量示例并行事件可见性决策类类的目的已知的问题类的开发/维护历史、版本注释出采用的不变量并行策略编译单元（文件）每一个类/类内定义的接口，含简单的说明文件名和/或标识信息修改/维护记录版权信息获取成员函数若可能，说明为什么使用滞后初始化接口目的它应如何被使用以及如何不被使用局部变量用处/目的成员函数注释成员函数做什么以及它为什么做这个哪些参数必须传递给一个成员函数成员函数返回什么已知的问题任何由某个成员函数抛出的异常可见性决策成员函数是如何改变对象的包含任何修改代码的历史如何在适当情况下调用成员函数的例子适用的前提条件和后置条件成员函数内部注释控制结构代码做了些什么以及为什么这样做局部变量文档名称Java开发规范版本文档编号日期2010-11-253.6其他注释应对重要的变量加以注释，以说明其含义等。应对不易理解的分支条件表达式加注释。不易理解的循环，应说明出口条件。过长的方法实现，应将其