Java 开发规范

第1页Java开发规范第2页绪论绪论目的本规范的目的是使本组织能以标准的、规范的方式设计和编码。通过建立编码规范，以使每个开发人员养成良好的编码风格和习惯；并以此形成开发小组编码约定，提高程序的可靠性、可读性、可修改性、可维护性和一致性等，增进团队间的交流，并保证软件产品的质量。参考资料《Java编程指南》见RUP（RationalUnifiedProcess）中文版。《Java技术手册》(JavainaNutshell)《SunJava语言编码规范》(JavaCodeConventions)《EffictiveJava》《JavaPitfalls》《JavaRules》概述对于代码，首要要求是它必须正确，能够按照设计预定功能去运行；第二是要求代码必须清晰易懂，使自己和其他的程序员能够很容易地理解代码所执行的功能等。然而，在实际开发中，每个程序员所写的代码却经常自成一套，很少统一，导致理解困难，影响团队的开发效率及系统的质量等。因此，一份完整并被严格执行的开发规范是非常必须的，特别是对软件公司的开发团队而言。最根本的原则：代码虽然是给机器运行的，但却是给人读的！代码组织与风格基本原则代码的组织和风格的基本原则是：便于自己的开发，易于与他人的交流。操作指南第3页代码的组织格式直接采用Eclipse内建的Formatter格式，使用Format功能组织文件即可。注释基本原则注释应该增加代码的清晰度。代码注释的目的是要使代码更易于被其他开发人员理解。如果你的程序不值得注释，那么它很可能也不值得运行。避免使用装饰性内容。保持注释的简洁。注释信息不仅要包括代码的功能，还应给出原因。不要为注释而注释。除变量定义等较短语句的注释可用行尾注释外，其他注释当避免使用行尾注释。JavaDoc注释操作指南对类/接口、非私有方法、非私有变量等的注释必须使用JavaDoc注释。操作指南：1)导入注释模版为Eclipse所有工程导入注释模版：a)菜单Window-Preferences，Java-CodeStyle-CodeTemplates；b)用Import命令导入附录1中的Eclipse代码注释模板文件。为Eclipse单个工程导入注释模版：a)菜单Project-Properties，JavaCodeStyle-CodeTemplates；b)用Import命令导入附录1中的Eclipse代码注释模板文件。2)编写Java类/接口时，在类/接口、非私有方法、非私有变量的上一行用/**前导并回车可自动产生JavaDoc注释的格式，将%x%修改为实际的内容。3)在非私有方法的JavaDoc注释的补充说明一般有参数有返回值有异常的方法自动生成的注释类似如下（不包括红色字体的内容）：/****%方法的一句话概述（注：句号不能删除，本注应删除）%。*p%方法详述（简单方法可不必详述）%/p*@params说明参数含义第4页*@return说明返回值含义*@throwsIOException说明发生此异常的条件*@throwsNullPointerException说明发生此异常的条件*/默认生成的JavaDoc注释没有这些红色字体的内容，它们必须被填入实际内容，才能产生优美格式的JavaDoc文档。其他以下情况必须添加注释：私有方法，除构造函数外，必须添加该方法的注释（JavaDoc注释或非JavaDoc注释均可）。复杂方法（如方法体超过30行），或包含关键算法的方法，必须对内部的操作步骤添加注释（行注释//或块注释/**/均可）。方法内部多次转换含义的变量，必须对该变量的含义发生变化时添加注释。方法内部存在不易理解的多个分支条件的表达式，必须对每个分支添加注释。对于引入的工程外、非Java内建类库的、不常见的包与类，在行末或上一行添加行注释。重要的包，必须添加注释。以下情况可不必添加注释：PO类的属性（私有变量），由于已经在get/set方法内添加JavaDoc注释，因此可不必添加。构造函数。配置文件注释非项目自有的应用或包的配置文件内增加新参数，或者需要维护人员修改的参数，必须增加注释，注释内容包括：含义，默认值，设置范围。项目自有的配置文件，必须为每个参数增加注释，注释内容包括：含义，默认值，设置范围。命名基本原则第5页规范的命名能使程序更易阅读，从而更易于理解。它们也可以提供一些标识功能方面的信息，有助于更好的理解代码和应用。使用可以准确说明变量/字段/类/接口/包等的完整的英文描述符。例如，采用类似firstName，listAllUsers或CorporateCustomer这样的名字，尽量不使用汉语拼音及不相关单词命名，严禁使用汉语拼音首字母组合命名，虽然Java支持Unicode命名，但本规范规定对包、类、接口、方法、变量、字段等不得使用汉字等进行命名。采用该领域的术语。如果用户称他们的“客户”(clients)为“顾客”(customers)，那么就采用术语Customer来命名这个类，而不用Client。采用大小写混合，提高名字的可读性。一般应该采用小写字母，但是类和接口的名字的首字母，以及任何中间单词的首字母应该大写。包名全部小写。避免使用长名字（最好不超过25个字母）。避免使用相似或者仅在大小写上有区别的名字。避免使用数字，但可用2代替to，用4代替for等，如：go2Jsp。文件、包文件名当与其类严格相同，所有单词首字母大写。包名一般以项目或模块名命名，少用缩写和长名，一律小写。基本包：com.aspire，所有包、文件都从属于此包。包名按如下规则组成：[基本包].[项目名].[模块名].[子模块名]...如：com.aspire.quasarcom.aspire.dao.oracle不得将类直接定义在基本包下，所有项目中的类、接口等都当定义在各自的项目和模块包中。类、接口所有单词首字母大写。使用能确切反应该类、接口含义、功能等的词。一般采用名词。接口可带I前缀或able、ible、er等后缀。第6页字段常量采用完整的英文大写单词，在词与词之间用下划线连接，如：DEFAULT_VALUE变量和参数对不易清楚识别出该变量类型的变量应使用类型缩写作其前缀，如字符串使用strXXX,boolean使用isXXX，hasXXX等等。除第一各个单词外其余单词首字母大写。对私有实例变量可使用_前缀，但在其存取方法中则应该将其前缀去掉。组件/部件应采用完整的英文描述符命名组件（接口部件），遵循匈牙利命名法则如：btnOK，lblName。集合一个集合，例如数组和矢量，应采用复数命名来表示队列中存放的对象类型。命名应采用完整的英文描述符，名字中所有非开头的单词的第一个字母应大写，适当使用集合缩写前缀。如：VectorvProducts=newVector();//产品向量ArrayaryUsers=newArray();//用户列表神秘的数在程序里经常会用到一些量，它是有特定的含义的。例如，现在我们写一个薪金统计程序，公司员工有50人，我们在程序里就会用50这个数去进行各种各样的运算。在这里，50就是神秘的数。当别的程序员在程序里看到50这个数，将很难知道它的含义，造成理解上的困难。在程序里出现神秘的数会降低程序的可读性、可维护性和可扩展性，故规定不得出现此类神秘的数。避免的方法是把神秘的数定义为一个常量。注意这个常量的命名应该能表达该数的意义，并且应该全部大写，以与对应于变量的标识符区别开来。例如上面50这个数，我们可以定义为一个名为NUM_OF_EMPLOYEES的常量来代替。这样，别的程序员在读程序的时候就可以容易理解了。其他命名时应使用复数来表示它们代表多值（数组）。如：orderItems。方法第7页方法的命名应采用完整的英文描述符，大小写混合使用：所有中间单词的第一个字母大写。方法名称的第一个单词常常采用一个有强烈动作色彩的动词。类中常用方法的命名：1.类的获取方法（一般具有返回值）一般要求在被访问的字段名前加上get，如getFirstName()，getLastName()。2.类的设置方法（一般返回类型为void）：被访问字段名的前面加上前缀set，如3.setFirstName(),setLastName().4.类的布尔型的判断方法一般要求方法名使用单词is做前缀，如isPersistent()isString()。或者使用具有逻辑意义的单词，例如equal或equals。5.类的普通方法一般采用完整的英文描述说明成员方法功能，第一个单词尽可能采用动词，首字母小写，如openFile（），addCount（）。6.构造方法应该用递增的方式写。（参数多的写在后面）。7.toString()方法：一般情况下，每个类都应该定义toString(),其格式为：publicStringtoString(){…}。异常异常类名由表示该异常类型的单词和Exception组成，如ActionException。异常实例一般使用e、ex等，在多个异常时使用该异常名或简写加E，Ex等组成，如：SQLExActionEx声明基本原则声明的基本原则是遵守Java语言规范，并遵从习惯用法。包在导入包时当完全限制代码所使用的类的名字,尽量少用通配符的方式，但导入一些通用包，或用到一个包下大部分类时，则可是使用通配符方式，如：第8页importcom.aspire.quasar.services.Service;importjava.util.*;同一包中的类导入时当声明在一起，可由编辑器自动完成此功能。重要的包当添加注释。类、接口类、接口定义语法规范：[可见性][('abstract'|'final')][Class|Interface]class_name[('extends'|'implements')][父类或接口名]{}如：publicclassLoginActionextendsBaseActionimplemnetsActionListener{}方法良好的程序设计应该尽可能减小类与类之间耦合，所遵循的经验法则是：尽量限制成员函数的可见性。如果成员函数没必要公有(public)，就定义为保护(protected)；没必要保护(protected)，就定义为私有(private)。方法定义语法规范：[可见性][('abstract'|'final')]['synchronized'][返回值类型]method_name(参数列表)[('throws')][异常列表]{//功能模块}如：publicListlistAllUsers()throwsDAOException{}若有toString(),equals(),hashCode(),colone()等重载自Object的方法，应将其放在类的最后。第9页声明顺序：构造方法静态公共方法公共方法静态私有方法受保护方法私有方法继承自Object的方法字段字段定义语法规范：[(‘public’|’private’|’protected’)][(‘final’|’volatile’)][‘static’][‘transient’]data_typefield_name[‘=’expression]‘;’若没有足够理由，不要把实例或类变量声明为公有。公共和保护的可见性应当尽量避免，所有的字段都建议置为私有，由获取和设置成员函数（Getter、Setter）访问。不允许“隐藏”字段，即给局部变量所取的名字，不可与另一个更大范围内定义的字段的名字相同（或相似）。例如，如果把一个字段叫做firstName，就不要再生成一个局部变量叫做firstName，或者任何易混肴的名字，如fistName。数组声明时当将[]跟在类型后，而不是字段名后，如：Integer[]ai=newInteger[2];//一个整数对象数组，用于...Integeraj[]=newInteger[3];//不要用这种数组声明方式一行代码