JAVA开发编码规范1.2.doc

江苏亿科达科技发展有限公司

江苏亿科达科技发展有限公司
JAVA开发编码规范

版 本 说 明

版本
制订人
制订日期
主要内容
V1.0
夏霆
2008-09-11
JAVA开发编码规范初稿
V1.1
田路
2008-10-31
JAVA开发编码规范修改
V1.2
夏霆
2008-10-31
确认发布

一、 前言 3
1.1、 目的 3
1.2、范围 4
二、 格式规范 4
2.1 缩进 5
2.2 换行 5
2.3 间隔 5
2.4 对齐 5
2.5 括号 5
三、注释规范 6
3.1 基本原则 6
3.2 文件注释 6
3.3 Java Doc 注释 6
3.4 失效代码注释 7
3.5 代码细节注释 7
3.6 注释的格式 8
3.7 注释的内容 8
3.8 Null 规约 8
4 命名规范(Naming Conventions) 9
4.1 基本约定 10
4.2 文件、包 10
4.3 类、接口 10
4.4 字段 10
5 编程规范(Programming Conventions) 11
5.1 基本规范 11
5.2 类与接口 12
5.3 方法 12
5.4 错误与异常 13
5.5 JDK5.0 及后续版本 14
5.6 性能与安全 14
6 自动代码检查和修正 15
6.1 为了编码的一致性，统一将Workspace中的编码方式设置为UTF-8编码 15
6.2使用统一的代码模板 16

一、 前言
1.1、 目的
本规范的目的是通过建立编码规范统一每个开发人员的编码习惯，提高程序的可靠性、可读性、可修改性、可维护性及一致性，增加团队合作开发效率，为各项目组之间或项目组内成员之间的技术交流提供一个方便统一的方式。

1.2、范围
本规范适用于公司内所有运用JAVA技术的软件项目、产品等的设计、开发以及维护、升级等。
本规范适用于公司所有JAVA软件开发人员。
本规范建议的开发环境与工具如下：
IDE:Eclipse3.3.2以后版本
插件:MyEclipse6.0以后版本
JDK: Sun JDK 1.5

二、 格式规范
对于代码，首要要求是它必须正确，能够按照设计预定功能去运行；第二是要求代码必须清晰易懂，使软件开发团队中的程序员能够很容易地理解代码。
代码的组织和风格的基本原则是：便于自己的开发，易于与他人的交流。
因个人习惯和编辑器等可以设置和形成自己的风格，但必须前后一致，并符合本规范的基本要求和原则。
2.1 缩进
使用TAB 缩进，而不是空格键——将缩进2，4，8 字符的选择权留给阅读者。
子功能块当在其父功能块后缩进。当功能块过多而导致缩进过深时当将子功能块提取出来做为子函数。
2.2 换行
页宽应该设置为80 字符。一般不要超过这个宽度, 这会导致在某些机器中或打印（A4）时无法以一屏来完整显示, 但这一设置也可以灵活调整。在任何情况下, 超长的语句应该在一个逗号后或一个操作符。
前折行。一条语句折行后, 应该比原来的语句再缩进一个TAB，以便于阅读。
2.3 间隔
类、方法及功能块间等应以空行相隔，以增加可读性，但不得有无规则的大片空行。操作符两端应当各空一个字符以增加可读性。相应独立的功能模块之间可使用注释行间隔，并标明相应内容。
2.4 对齐
关系密切的行应对齐，对齐包括类型、修饰、名称、参数等各部分对齐。连续赋值时应当对齐操作符。当方法参数过多时在适当的参数后（逗号后）换行并对齐。当控制或循环中的条件比较长时当换行（操作符前）、对齐并注释各条件。
2.5 括号
括号中的语句应该单独作为一行，左括号"{"当紧跟其语句后，右括号"}"永远单独作为一行且与其匹配行对齐，并尽量在其后说明其匹配的功能模块。
较长的方法以及类、接口等的右括号后应使用//end ...等标识其结束。如:
类的结束符：}//end ClassName，
方法结束符：}//end methodName()，
功能块结束：}//end if...userName is null?
循环快结束：}//end for...every user in userList
不要在程序中出现不必要的括号，但有时为了增加可读性和便于理解，当用括号限定相应项。
If，for，while 语句只有单句时，如果该句可能引起阅读混淆，需要用"{"和"}"括起来，否则可以省略。

三、注释规范
3.1 基本原则
基本原则：注释应该增加代码的清晰度。代码注释的目的是要使代码更易于被其他开发人员等理解。
注释信息不仅要包括代码的功能，还应给出原因。
除变量定义等较短语句的注释可用行尾注释外，其他注释当避免使用行尾注释。
3.2 文件注释
在每个文件、包的头部都应该包含该文件的功能、作用、作者、版权以及创建、修改记录等。并在其中使用版本仓库标记自动跟踪版本变化及修改记录等信息。注意是标准的C-Style/*...*/ 注释而不是/* ...*/ 形式的JavaDoc 注释，在ECLIPS中使用CODE TEMPLATES会自动添加，如下。
/*
* @(#) Test1.java
* Created Date: Sep 11, 2008
*
* Copyright (c) Jiangsu Ecode Co., Ltd
*
* This software is the confidential and proprietary information of
* Jiangsu Ecode Co., Ltd. ("Confidential Information"). You shall not
* disclose such Confidential Information and shall use it only in accordance
* with the terms of the license agreement you entered into with
* Jiangsu Ecode Co., Ltd.
*/

3.3 Java Doc 注释
对类、方法、变量等的注释需要符合JavaDoc 规范，对每个类、方法都应详细说明其功能、条件、参数等，并使用良好的HTML 标记格式化注释，以使生成的JavaDoc易阅读和理解。
类注释中当包含版本和作者信息，使用版本仓库的标记自动跟踪版本变化和修改记
录，如下。
/**
* 用于示例的类
*
* @author <a href="mailto:xiating@">Xiating</a>
* @version $Rev$ <br>
* $Id: Test1.java,v 1.2 2008/09/17 02:25:08 cvsroot Exp $
*/
public class Test1 {
private static final Logger logger = Logger.getLogger(Test1.class);

/**
*一个测试的方法
*@param userid 用户编号
*@return 返回用户信息对象，若无该用户信息，则返回null
*/
private UserInfo getStrings(Integer userid) {
……………
return userInfo;
}
}
3.4 失效代码注释
由/*...*/界定，标准的C-Style 的注释。专用于注释已失效的代码。
/*username = "";
password = "";
currentCar = "";
logined = false;
attributes = new HashMap();
attributes.put("title", "hello");*/
失效注释快捷键是Ctrl+Shift+/ ，取消注释是Ctrl+Shift+\

3.5 代码细节注释
由// 界定，专用于注释代码细节，即使有多行注释也仍然使用//，以便与用/**/注
释的失效代码分开除了私有变量外，不推荐使用行末注释。
//设置CarBean
for(int i=0; i < 20; i++)
{
//首先需要生成实例
CarBean bean = new CarBean();
bean.setBaseprice(11);
bean.setDescription("aa");
bean.setName("1111");
cdao.save(bean);
}

3.6 注释的格式
l 注释中的第一个句子要以（英文）句号、问号或者感叹号结束。Javadoc 生成工具会将注释中的第一个句子放在方法汇总表和索引中。
l 为了在JavaDoc 和IDE 中能快速链接跳转到相关联的类与方法，尽量多的使用@see xxx.MyClass，@see xx.MyClass#find(String)。
l Class 必须以@author 作者名声明作者，不需要声明手工指定@version 与@date，由版本管理系统保留此信息。
l 如果注释中有超过一个段落，用<p>分隔。
l 示例代码以<pre></pre>包裹。
l 标识(java keyword, class/method/field/argument 名，Constants) 以<code></code>包裹。
l 标识在第一次出现时以{@linkxxx.Myclass}注解以便JavaDoc 与IDE 中可以链接。

3.7 注释的内容
l 对于API 函数如果存在契约，必须写明它的前置条件(precondition)，后置条件(postcondition)，及不变式(invariant)。
l 对于调用复杂的API 尽量提供代码示例。
l 对于已知的Bug 需要声明。
l 在本函数中抛出的unchecked exception 尽量用@throws 说明。
l 注释中的每一个单词都要有其不可缺少的意义，注释里不写"@param name -名字"无意义的内容。
l 注释的标签必须有内容，不能存在空的@param name，空的@return。

3.8 Null 规约
如果方法允许Null 作为参数，或者允许返回值为Null，必须在JavaDoc 中说明。
如果没有说明，方法的调用者不允许使用Null 作为参数，并认为返回值是Null Safe的。

/**
*
* @param actionEvent 买车按钮的动作事件
* @throws Exception 一般异常
*/
public void buyCar(ActionEvent actionEvent) throws Exception
{
}

4 命名规范(Naming Conventions)
规范的命名能使程序更易阅读，从而更易于理解。它们也可以提供一些标识功能方面的信息，有助于更好的理解代码和应用。
4.1 基本约定
l 使用可以准确说明变量/字段/类/接口/包等的完整的英文描述符。例如，采用类似firstName，listAllUsers 或CorporateCustomer 这样的名字，严禁使用汉语拼音及不相关单词命名，虽然Java 支持Unicode 命名，但本规范规定对包、类、接口、方法、变量、字段等不得使用汉字等进行命名。
l 采用该领域的术语。如果用户称他们的“客户”(clients) 为“顾客”(customers)，那么就采用术语Customer 来命名这个类，而不用Client。
l 采用大小写混合，提高名字的可读性。一般应该采用小写字母，但是类和接口的名字的首字母，以及任何中间单词的首字母应该大写。包名全部小写。
l 尽量少用缩写，但如果一定要使用，当使用公共缩写和习惯缩写等，如实现（implement）可缩写成impl，应用程序（application）可缩写成app 等，严禁滥用缩写。
l 避免使用长名字（最好不超过25 个字母）。
l 避免使用相似或者仅在大小写上有区别的名字。
l 避免使用数字，但可用2 代替to，用4 代替for 等，如：go2Jsp。
l 遇到缩写如XML 时， 仅首字母大写， 即loadXmlDocument() 而不是loadXMLDocument()。

4.2 文件、包
l 文件名当与其类严格相同，所有单词首字母大写。
l 包名一般以项目或模块名命名，少用缩写和长名，一律小写。
l 基本包：com.candur，所有包、文件都从属于此包。
l 包名按规则组成：[基本包] . [项目名] . [模块名] . [子模块名]...
l 不得将类直接定义在基本包下，所有项目中的类、接口等都当定义在各自的项目和模块包中。

4.3 类、接口
所有单词首字母大写。使用能确切反应该类、接口含义、功能等的词。一般采用名词。接口可以可以在名词前加大写I，如IBookDao,，BookDaoIF。

4.4 字段
4.4.1 常量

采用完整的英文大写单词，在词与词之间用下划线连接，如：DEFAULT_VALUE

4.4.2 变量和参数

对不易清楚识别出该变量类型的变量应使用类型缩写作其前缀，如字符串使用strXXX，boolean 使用isXXX，hasXXX 等等。除第一各个单词外其余单词首字母大写。对私有实例变量可使用下划线“_”前缀，但在其存取方法中则应该将其前缀去掉。局部变量及输入参数不要与类成员变量同名(get/set 方法与构造函数除外)。

4.4.3 组件/部件

应采用完整的英文描述符命名组件（接口部件），遵循匈牙利命名法则页面部件名建议命名为：btnOK、lblName 或okBtn、nameLbl。(II)

4.4.4 集合

一个集合，例如数组和矢量，应采用复数命名来表示队列中存放的对象类型。命名应采用完整的英文描述符，名字中所有非开头的单词的第一个字母应大写，适当使用集合缩写前缀。如：__

5 编程规范(Programming Conventions)
声明的基本原则是遵守Java 语言规范，并遵从习惯用法。。
5.1 基本规范
l 当面对不可知的调用者时，方法需要对输入参数进行校验，如不符合抛出IllegalArgumentException，建议使用Spring 的Assert 系列函数。
l 隐藏工具类的构造器，确保只有static 方法和变量的类不能被构造实例。
l 变量，参数和返回值定义尽量基于接口而不是具体实现类。如：
l 代码中不能使用System.out.println()，e.printStackTrace()，必须使用logger 打印信息。

5.2 类与接口
5.2.1 基本原则

l 类的划分粒度，不可太大，造成过于庞大的单个类，也不可太细，从而使类的继承太深。一般而言，一个类只做一件事；另一个原则是根据每个类的职责进行划分，比如用User 来存放用户信息，而用UserDAO 来对用户信息进行数据访问操作（比如存取数据库），用UserBroker 来封装用户信息的业务操作等等。
l 多使用设计模式，随时重构。
l 多个类中使用相同方法时将其方法提到一个接口中或使用抽象类，尽量提高重用度。
l 将不希望再被继承的类声明成final，例如某些实用类，但不要滥用final，否则会对系统的可扩展性造成影响。
l 将不希望被实例化的类的缺省构造方法声明成private。

5.2.2 抽象类与接口

一般而言：接口定义行为，而抽象类定义属性和公有行为，注意两者间的取舍，在设计中，可由接口定义公用的行为，由一个抽象类来实现其部分或全部方法，以给子类提供统一的行为定义，可参考Java 集合等实现。
多使用接口，尽量做到面向接口的设计，以提高系统的可扩展性。

5.2.3 继承与组合

尽量使用组合来代替继承，一则可以使类的层次不至于过深，而且会使类与类，包与包之间的耦合度更小，更具可扩展性。

5.2.4 构造函数和静态工厂方法

当需要使用多个构造函数创建类时，建议使用静态工厂方法替代这些构造方法。
5.3 方法
5.3.1 基本原则

l 一个方法只完成一项功能，在定义系统的公用接口方法外的方法应尽可能的缩
小其可见性。
l 避免用一个类是实例去访问其静态变量和方法。
l 避免在一个较长的方法里提供多个出口。

5.3.2 参数和返回值

l 避免过多的参数列表，尽量控制在5 个以内，若需要传递多个参数时，当使
用一个容纳这些参数的对象进行传递，以提高程序的可读性和可扩展性。
l 参数类型和返回值尽量接口化，以屏蔽具体的实现细节，提高系统的可扩展性。

5.4 错误与异常
5.4.1 基本原则

l 通常的思想是只对错误采用异常处理：逻辑和编程错误，设置错误，被破坏的
数据，资源耗尽，等等。
l 通常的法则是系统在正常状态下以及无重载和硬件失效状态下，不应产生任何
异常。
l 最小化从一个给定的抽象类中导出的异常的个数。
l 对于经常发生的可预计事件不要采用异常。
l 不要使用异常实现控制结构。
l 确保状态码有一个正确值。
l 在本地进行安全性检查，而不是让用户去做。
l 若有finally 子句，则不要在try 块中直接返回，亦不要在finally 中直接返
回。

5.4.2 已检查异常与运行时异常

l 已检查异常必须捕捉并做相应处理，不能将已检查异常抛到系统之外去处理。
l 对可预见的运行时异常当进行捕捉并处理，比如空指针等。通常，对空指针的
判断不是使用捕捉NullPointException 的方式，而是在调用该对象之前使用判
断语句进行直接判断。
l 建议使用运行时异常(RuntimeException)代替已检查异常（CheckedException）。

5.4.3 异常处理

l 重新抛出的异常必须保留原来的异常，即throw new NewException("message",
e); 而不能写成throw new NewException("message")。
l 在所有异常被捕获且没有重新抛出的地方必须写日志，避免异常的湮没。
l 如果属于正常异常的空异常处理块必须注释说明原因，否则不允许空的catch
块。
l 框架尽量捕获低级异常，并封装成高级异常重新抛出，隐藏低级异常的细节。

l 多个异常应分别捕捉并处理，避免使用一个单一的catch 来处理。
5.5 JDK5.0 及后续版本
l 重载方法必须使用@Override，可避免父类方法改变时导致重载函数失效
l 不关心的warning 信息用@SuppressWarnings("unused")，@SuppressWarnings("unchecked"),@SuppressWarnings("serial") 注释掉。

5.6 性能与安全
5.6.1 String 与StringBugffer

不要使用如下String 初始化方法：
String str = new String(“abcdef”);
这将产生两个对象，应当直接赋值：
String str = “abcdef”;
在处理可变String 的时候要尽量使用StringBuffer 类，StringBuffer 类是构成String 类的基础。String 类将StringBuffer 类封装了起来，（以花费更多时间为代价）为开发人员提供了一个安全的接口。当我们在构造字符串的时候，我们应该用StringBuffer 来实现大部分的工作，当工作完成后将StringBuffer 对象再转换为需要的String 对象。比如：如果有一个字符串必须不断地在其后添加许多字符来完成构造，那么我们应该使用StringBuffer 对象和她的append() 方法。如果我们用String 对象代替StringBuffer 对象的话，将会花费许多不必要的创建和释放对象的CPU 时间。

5.6.2 集合

避免使用Vector 和HashTable 等旧的集合实现，这些实现的存在仅是为了与旧的系统兼容，而且由于这些实现是同步的，故而在大量操作时会带来不必要的性能损失。在新的系统设计中不当出现这些实现，使用ArrayList 代替Vector，使用HashMap 代替HashTable。
若却是需要使用同步集合类，当使用如下方式获得同步集合实例：
Map map = Collections.synchronizedMap(new HashMap());
由于数组、ArrayList 与Vector 之间的性能差异巨大（具体参见《Java fitball》），故在能使用数组时不要使用ArrayList，尽量避免使用Vector。

5.6.3 对象

l 避免在循环中频繁构建和释放对象。
l 不再使用的对象应及时销毁。
l 如无必要，不要序列化对象

5.6.4 同步

l 在不需要同步操作时避免使用同步操作类，如能使用ArrayList 时不要使用
Vector。
l 尽量少用同步方法，避免使用太多的synchronized 关键字。
l 尽量将同步最小化，即将同步作用到最需要的地方，避免大块的同步块或方法
等。

5.6.5 final

l 将参数或方法声明成final 可提高程序响应效率，故此：
l 注意绝对不要仅因为性能而将类、方法等声明成final，声明成final 的类、方法一定要确信不再被继承或重载！
l 不需要重新赋值的变量（包括类变量、实例变量、局部变量）声明成final。
l 所有方法参数声明成final。
l 私有(private)方法不需要声明成final。
l 若方法确定不会被继承，则声明成final。

5.6.6 垃圾收集和资源释放

不要过分依赖JVM 的垃圾收集机制，因为你无法预测和知道JVM 在什么时候运行GC。尽可能早的释放资源，不再使用的资源请立即释放。
可能有异常的操作时必须在try 的finally 块中释放资源，如数据库连接、IO 操
作等。

6 自动代码检查和修正
6.1 为了编码的一致性，统一将Workspace中的编码方式设置为UTF-8编码

6.2使用统一的代码模板
首先，需要加载指定的代码模板，打开Code Templates后选择Comments，再点击Import，将jsecode_eclipse_codetemplates.xml模板导入。

其次，在创建类或者接口的时候需要勾选 Generate comments

代码模板导入之后，请修改注释中的作者部分，改写为您自己的联系方式和名称。
18/18