Java 开发规范.doc

Java_开发规范Java 开发规范
绪论
绪论
目的
本规范的目的是使本组织能以标准的、规范的方式设计和编码。通过建立编码规范,以使每个开发人员养成良好的编码风格和习惯;并以此形成开发小组编码约定,提高程序的可靠性、可读性、可修改性、可维护性和一致性等,增进团队间的交流,并保证软件产品的质量。
参考资料
《Java 编程指南》见RUP(Rational Unified Process)中文版。
《Java 技术手册》(Java in a Nutshell)
《Sun Java 语言编码规范》(Java Code Conventions)
《Effictive Java》
《Java Pitfalls》
《Java Rules》
概述
对于代码,首要要求是它必须正确,能够按照设计预定功能去运行;第二是要求代码必须清晰易懂,使自己和其他的程序员能够很容易地理解代码所执行的功能等。然而,在实际开发中,每个程序员所写的代码却经常自成一套,很少统一,导致理解困难,影响团队的开发效率及系统的质量等。因此,一份完整并被严格执行的开发规范是非常必须的,特别是对软件公司的开发团队而言。
最根本的原则:
代码虽然是给机器运行的,但却是给人读的!
代码组织与风格
基本原则
代码的组织和风格的基本原则是:便于自己的开发,易于与他人的交流。
操作指南
代码的组织格式直接采用Eclipse内建的Formatter格式,使用Format功能组织文件即可。
注释
基本原则
注释应该增加代码的清晰度。代码注释的目的是要使代码更易于被其他开发人员理解。
如果你的程序不值得注释,那么它很可能也不值得运行。
避免使用装饰性内容。
保持注释的简洁。
注释信息不仅要包括代码的功能,还应给出原因。
不要为注释而注释。
除变量定义等较短语句的注释可用行尾注释外,其他注释当避免使用行尾注释。
JavaDoc注释操作指南
对类/接口、非私有方法、非私有变量等的注释必须使用JavaDoc注释。
操作指南:
1) 导入注释模版
为Eclipse所有工程导入注释模版:
菜单Window->Preferences,Java->Code Style->Code Templates;
用Import命令导入附录1中的Eclipse代码注释模板文件。
为Eclipse单个工程导入注释模版:
菜单Project->Properties,Java Code Style->Code Templates;
用Import命令导入附录1中的Eclipse代码注释模板文件。
2) 编写Java类/接口时,在类/接口、非私有方法、非私有变量的上一行用/**前导并回车可自动产生JavaDoc注释的格式,将%x%修改为实际的内容。
3) 在非私有方法的JavaDoc注释的补充说明
一般有参数有返回值有异常的方法自动生成的注释类似如下(不包括红色字体的内容):
/**
*
* %方法的一句话概述(注:句号不能删除,本注应删除)%。
* <p>%方法详述(简单方法可不必详述)%</p>
* ***@param s 说明参数含义
* ***@return 说明返回值含义
* ***@throws IOException 说明发生此异常的条件
* ***@throws NullPointerException 说明发生此异常的条件
*/
默认生成的JavaDoc注释没有这些红色字体的内容,它们必须被填入实际内容,才能产生优美格式的JavaDoc文档。
其他
以下情况必须添加注释:
私有方法,除构造函数外,必须添加该方法的注释(JavaDoc注释或非JavaDoc注释均可)。
复杂方法(如方法体超过30行),或包含关键算法的方法,必须对内部的操作步骤添加注释(行注释//或块注释/* */均可)。
方法内部多次转换含义的变量,必须对该变量的含义发生变化时添加注释。
方法内部存在不易理解的多个分支条件的表达式,必须对每个分支添加注释。
对于引入的工程外、非Java内建类库的、不常见的包与类,在行末或上一行添加行注释。
重要的包,必须添加注释。
以下情况可不必添加注释:
PO类的属性(私有变量),由于已经在get/set方法内添加JavaDoc注释,因此可不必添加。
构造函数。
配置文件注释
非项目自有的应用或包的配置文件内增加新参数,或者需要维护人员修改的参数,必须增加注释,注释内容包括:含义,默认值,设置范围。
项目自有的配置文件,必须为每个参数增加注释,注释内容包括:含义,默认值,设置范围。
命名
基本原则
规范的命名能使程序更易阅读,从而更易于理解。它们也可以提供一些标识功能方面的信息,有助于更好的