Java 开发规范.doc

第页

第页
Java开发规范
绪论
绪论
目的
本规范的目的是使本组织能以标准的、规范的方式设计和编码。通过建立编码规范，以使每个开发人员养成良好的编码风格和习惯；并以此形成开发小组编码约定，提高程序的可靠性、可读性、可修改性、可维护性和一致性等，增进团队间的交流，并保证软件产品的质量。
参考资料
《Java编程指南》见RUP（RationalUnifiedProcess）中文版。
《Java技术手册》(JavainaNutshell)
《SunJava语言编码规范》(JavaCodeConventions)
《EffictiveJava》
《JavaPitfalls》
《JavaRules》
概述
对于代码，首要要求是它必须正确，能够按照设计预定功能去运行；第二是要求代码必须清晰易懂，使自己和其他的程序员能够很容易地理解代码所执行的功能等。然而，在实际开发中，每个程序员所写的代码却经常自成一套，很少统一，导致理解困难，影响团队的开发效率及系统的质量等。因此，一份完整并被严格执行的开发规范是非常必须的，特别是对软件公司的开发团队而言。
最根本的原则：
代码虽然是给机器运行的，但却是给人读的！

代码组织与风格

基本原则
代码的组织和风格的基本原则是：便于自己的开发，易于与他人的交流。
操作指南
代码的组织格式直接采用Eclipse内建的Formatter格式，使用Format功能组织文件即可。
注释

基本原则

注释应该增加代码的清晰度。代码注释的目的是要使代码更易于被其他开发人员理解。
如果你的程序不值得注释，那么它很可能也不值得运行。
避免使用装饰性内容。
保持注释的简洁。
注释信息不仅要包括代码的功能，还应给出原因。
不要为注释而注释。
除变量定义等较短语句的注释可用行尾注释外，其他注释当避免使用行尾注释。
JavaDoc注释操作指南
对类/接口、非私有方法、非私有变量等的注释必须使用JavaDoc注释。
操作指南：
1)导入注释模版
为Eclipse所有工程导入注释模版：
菜单Window->Preferences，Java->CodeStyle->CodeTemplates；
用Import命令导入附录1中的Eclipse代码注释模板文件。
为Eclipse单个工程导入注释模版：
菜单Project->Properties，JavaCodeStyle->CodeTemplates；
用Import命令导入附录1中的Eclipse代码注释模板文件。
2)编写Java类/接口时，在类/接口、非私有方法、非私有变量的上一行用/**前导并回车可自动产生JavaDoc注释的格式，将%x%修改为实际的内容。
3)在非私有方法的JavaDoc注释的补充说明
一般有参数有返回值有异常的方法自动生成的注释类似如下（不包括红色字体的内容）：
/**
*
*%方法的一句话概述（注：句号不能删除，本注应删除）%。
*<p>%方法详述（简单方法可不必详述）%</p>
*@params说明参数含义
*@return说明返回值含义
*@throwsIOException说明发生此异常的条件
*@throwsNullPointerException说明发生此异常的条件
*/
默认生成的JavaDoc注释没有这些红色字体的内容，它们必须被填入实际内容，才能产生优美格式的JavaDoc文档。
其他
以下情况必须添加注释：
私有方法，除构造函数外，必须添加该方法的注释（JavaDoc注释或非JavaDoc注释均可）。
复杂方法（如方法体超过30行），或包含关键算法的方法，必须对内部的操作步骤添加注释（行注释//或块注释/**/均可）。
方法内部多次转换含义的变量，必须对该变量的含义发生变化时添加注释。
方法内部存在不易理解的多个分支条件的表达式，必须对每个分支添加注释。
对于引入的工程外、非Java内建类库的、不常见的包与类，在行末或上一行添加行注释。
重要的包，必须添加注释。
以下情况可不必添加注释：
PO类的属性（私有变量），由于已经在get/set方法内添加JavaDoc注释，因此可不必添加。
构造函数。

配置文件注释
非项目自有的应用或包的配置文件内增加新参数，或者需要维护人员修改的参数，必须增加注释，注释内容包括：含义，默认值，设置范围。
项目自有的配置文件，必须为每个参数增加注释，注释内容包括：含义，默认值，设置范围。
命名

基本原则
规范的命名能使程序更易阅读，从而更易于理解。它们也可以提供一些标识功能方面的信息，有助于更好的理解代码和应用。
使用可以准确说明变量/字段/类/接口/包等的完整的英文描述符。例如，采用类似firstName，listAllUsers或Cor