Java开发规范使用手册
目 录
第1章 绪论
1.1 编制依据
Java开发规程
1.2 目的和意义
本规范的目的是使本组织能以标准的、规范的方式设计和编码。通过建立编码规范，以使每个开发人员养成良好的编码风格和习惯；并以此形成开发小组编码约定，提高程序的可靠性、可读性、可修改性、可维护性和一致性等，增进团队间的交流，并保证软件产品的质量。
通过制定本规范，可以统一应用系统各软件的设计和开发，为下一步应用系统集成做好准备。各应用软件开发商通过遵循本规范，可以简化应用软件的开发，更好与其它软件协作，完成相关业务功能。
1.3 范围
本规范适用于“XXX”及其下所有软件项目、产品等的设计、开发以及维护、升级等。
本规范使用于“XXX”的所有软件开发人员，在整个软件开发过程中必须遵循此规范。
1.4 版权声明
本文档为杭州世平信息科技有限公司的内部开发规范，不得转载。未经杭州世平信息科技有限公司授权，任何个人、组织或单位不得将本文档用于书面发表、转载、摘录等，亦不得用于其他商业行为。
1.5 参考资料
1.6 概述
对于代码，首要要求是它必须正确，能够按照设计预定功能去运行；第二是要求代码必须清晰易懂，使自己和其他的程序员能够很容易地理解代码所执行的功能等。然而，在实际开发中，每个程序员所写的代码却经常自成一套，很少统一，导致理解困难，影响团队的开发效率及系统的质量等。因此，一份完整并被严格执行的开发规范是非常必须的，特别是对软件公司的开发团队而言。此规范参考自业界标准编程规范并结合多位编程高人多年编程经验、习惯等而制定。
最根本的原则：
代码虽然是给机器运行的，但却是给人读的！
运用常识。当找不到任何规则或指导方针，当规则明显不能适用，当所有的方法都失效的时侯：运用常识并核实这些基本原则。这条规则比其它所有规则都重要。常识是必不可少。
当出现该情况时，应当及时收集并提交，以便对本规范进行修改。
第2章 代码组织与风格
2.1 基本原则
代码的组织和风格的基本原则是：便于自己的开发，易于与他人的交流。
因个人习惯和编辑器等可以设置和形成自己的风格，但必须前后一致，并符合本规范的基本要求和原则。
本章所涉及到的内容一般都可在Java集成编辑环境中进行相应设置，也可由Ant等调用CheckStyle等来进行自动规整。
2.2 缩进
子功能块当在其父功能块后缩进。当功能块过多而导致缩进过深时当将子功能块提取出来做为子函数。
代码中以TAB（4个字符）缩进，在编辑器中请将TAB设置为以空格替代，否则在不同编辑器或设置下会导致TAB长度不等而影响整个程序代码的格式。例如：
Table1．缩进示例
| public void methodName(){ if(some condition) { for (…) { //some sentences }//end for }//end if } |
2.3 长度
为便于阅读和理解，单个函数的有效代码长度当尽量控制在100行以内（不包括注释行），当一个功能模块过大时(代码行数大于200行以上)往往造成阅读困难，因此当使用子函数等将相应功能抽取出来，这也有利于提高代码的重用度。
单个类也不宜过大，当出现此类情况时当将相应功能的代码重构到其他类中，通过组合等方式来调用，建议单个类的长度包括注释行不超过1500行。
尽量避免使用大类和长方法。
2.4 行宽
页宽应该设置为80字符。一般不要超过这个宽度, 这会导致在某些机器中无法以一屏来完整显示, 但这一设置也可以灵活调整。在任何情况下, 超长的语句应该在一个逗号后或一个操作符前折行。一条语句折行后, 应该比原来的语句再缩进一个TAB或4个空格，以便于阅读。
2.5 间隔
类、方法及功能块间等应以空行相隔，以增加可读性，但不得有无规则的大片空行。
操作符两端应当各空一个字符以增加可读性。
相应独立的功能模块之间可使用注释行间隔，并标明相应内容，具体参看附录的代码示例
2.6 对齐
关系密切的行应对齐，对齐包括类型、修饰、名称、参数等各部分对齐。
连续赋值时当对齐操作符。
当方法参数过多时当在每个参数后（逗号后）换行并对齐。
当控制或循环中的条件比较长时当换行（操作符前）、对齐并注释各条件。
变量定义最好通过添加空格形成对齐，同一类型的变量应放在一起。如下例所示：
Table2．对齐示例
| //变量对齐----------------------------------------------- int count = 100; int length = 0; String strUserName = null; Integer[] porductCode = new Integer(2); //产品编码数组 //参数对齐---------------------------------------------- public Connection getConnection(String url, String userName, String password) throws SQLException,IOException{ } //换行对齐---------------------------------------------- public final static String SQL_SELECT_PRODUCT = “SELECT * “ + “ FROM TProduct WHERE Prod_ID = ” + “prodID”; //条件对齐---------------------------------------------- if( Condition1 //当条件一 && Condition2 //并且条件二 || Condition3){ //或者条件三
//Code************************ } for(int i = 0; i < productCount.length; //循环终止条件 i++){
//Code************************
} |
2.7 括号
{} 中的语句应该单独作为一行，左括号"{"当紧跟其语句后，右括号"}"永远单独作为一行且与其匹配行对齐，并尽量在其后说明其匹配的功能模块。
较长的方法以及类、接口等的右括号后应使用//end ...等标识其结束。如:
类的结束符：}//EOCClassName，
方法结束符：}//endmethodName()，
功能块结束：}//endif...userName is null?
循环快结束：}//endfor...every user in userList
不要在程序中出现不必要的括号，但有时为了增加可读性和便于理解，当用括号限定相应项。
左括号是否换行等随个人习惯而定，若换行则当与其前导语句首字符对齐。
第3章 注释
3.1 基本原则
1) 注释应该增加代码的清晰度。代码注释的目的是要使代码更易于被其他开发人员等理解。
2) 如果你的程序不值得注释，那么它很可能也不值得运行。
3) 避免使用装饰性内容。
4) 保持注释的简洁。
5) 注释信息不仅要包括代码的功能，还应给出原因。
6) 不要为注释而注释。
7) 除变量定义等较短语句的注释可用行尾注释外，其他注释当避免使用行尾注释。
3.2 JavaDoc
对类、方法、变量等的注释需要符合JavaDoc规范，对每个类、方法都应详细说明其功能、条件、参数等，并使用良好的HTML标记格式化注释，以使生成的JavaDoc易阅读和理解。
类注释中当包含版本和作者信息，使用SVN标记自动跟踪版本变化和修改记录，具体内容参见《SVN使用手册》及下面几节的相应内容等，SVN标识符请参加附录中的《SVN标识符》。
3.3 文件与包注释
在每个文件、包的头部都应该包含该文件的功能、作用、作者、版权以及创建、修改记录等。并在其中使用SVN标记自动跟踪版本变化及修改记录等信息。注意是/**/注释而不是/***/JavaDoc注释。
文件注释模板见附件《注释模板》中的文件注释部分。
版权声明部分请参见附件《版权声明》并注意更新到最新版本。
Table3 文件注释示例：
| /* ============================================================ * $Id: User.java,v 1.1 2002/09/07 14:36:23 l_zhy Exp $ * Created: [2003-3-23 20:18:53] by l_zhy * ============================================================ * * ProjectName * * Description * * ============================================================ * * Copyright Information. * * ===========================================================*/ |
每个包当有包注释，在源码及JavaDoc相应包路径下建立package.html以描述包的功能、作用等。
3.4 类、接口注释
在类、接口定义之前当对其进行注释，包括类、接口的目的、作用、功能、继承于何种父类，实现的接口、实现的算法、使用方法、示例程序等，在作者和版本域中使用SVN标记自动跟踪版本变化等，具体参看附件《注释模板》中相关部分。
Table4 类注释示例
| /** * <p>字符串实用类。</p> * * 定义字符串操作时所需要用到的方法，如转换中文、HTML标记处理等。 * * @author $Author: l_zhy$ * @version $Revision: 1.2 $ $Date: 2003/05/15 02:10:27 $ */ public class StringUtil { ⋯ } |
3.5 方法注释
依据标准JavaDoc规范对方法进行注释，以明确该方法功能、作用、各参数含义以及返回值等。复杂的算法用/**/在方法内注解出。
参数注释时当注明其取值范围等
返回值当注释出失败、错误、异常时的返回情况。
异常当注释出什么情况、什么时候、什么条件下会引发什么样的异常
Table5 方法注释示例
| /** * 执行查询。 * * 该方法调用Statement的executeQuery(sql)方法并返回ResultSet *结果集。 * * @param sql 标准的SQL语句 * @param sql 标准的SQL语句 * @return ResultSet结果集，若查询失败则返回null * @throws SQLException 当查询数据库时可能引发此异常 * @see */ public ResultSet executeQuery(String sql) throws SQLException { //Statement和SQL语句都不能为空 if(null != stmt && !StringUtil.isEmpty(sql)) { //返回查询执行结果 return stmt.executeQuery(sql); } return null; }//end executeQuery() |
3.6 其他注释
应对重要的变量加以注释，以说明其含义等。
应对不易理解的分支条件表达式加注释。不易理解的循环，应说明出口条件。过长的方法实现，应将其语句按实现的功能分段加以概括性说明。
对于异常处理当注明正常情况及异常情况或者条件，并说明当异常发生时程序当如何处理。
3.7 注释参考表
Table6 注释参考表
| 序号 | 项目 | 注释内容 |
| 1 | 参数 | 参数类型 参数用来做什么 约束或前提条件 示例 |
| 2 | 字段/属性 | 字段描述 注释所有使用的常量 示例 并行事件 可见性决策 |
| 3 | 类 | 类的目的 已知的问题 类的开发/维护历史、版本 注释出采用的常量 并行策略 |
| 4 | 编译单元 （文件） | 每一个类/类内定义的接口，含简单的说明 文件名和/或标识信息 修改/维护记录 版权信息 |
| 5 | 获取成员函数 | 若可能，说明为什么使用滞后初始化 |
| 6 | 接口 | 目的明确它应如何被使用以及如何不被使用 |
| 7 | 局部变量 | 用处/目的 |
| 8 | 成员函数注释 | 成员函数做什么以及它为什么做这个 哪些参数必须传递给一个成员函数 成员函数返回什么 已知的问题 任何由某个成员函数抛出的异常 可见性决策 成员函数是如何改变对象的 包含任何修改代码的历史 如何在适当情况下调用成员函数的例子 适用的前提条件和 后置条件 |
| 9 | 成员函数内部注释 | 控制结构 代码做了些什么以及为什么这样做 局部变量 难或复杂的代码 处理顺序 |
| 10 | 包 | 包的功能和用途 |
第4章 命名
4.1 基本原则
规范的命名能使程序更易阅读，从而更易于理解。它们也可以提供一些标识功能方面的信息，有助于更好的理解代码和应用。
1) 使用可以准确说明变量/字段/类/接口/包等的完整的英文描述符。例如，采用类似 firstName，listAllUsers 或 CorporateCustomer 这样的名字(采用驼峰式命名)，严禁使用汉语拼音及不相关单词命名，虽然Java支持Unicode命名，但本规范规定对包、类、接口、方法、变量、字段等不得使用汉字等进行命名。
2) 采用该领域的术语。如果用户称他们的“客户” (clients) 为“顾客” (customers)，那么就采用术语 Customer 来命名这个类，而不用 Client。
3) 采用大小写混合，提高名字的可读性。一般应该采用小写字母，但是类和接口的名字的首字母，以及任何中间单词的首字母应该大写。包名全部小写。
4) 尽量少用缩写，但如果一定要使用，当使用公共缩写和习惯缩写等，如实现（implement）可缩写成impl，经理（manager）可缩写成mgr等，具体参看附录之《常用缩写简表》，严禁滥用缩写。
5) 避免使用长名字（最好不超过 25 个字母）。
6) 避免使用相似或者仅在大小写上有区别的名字。
7) 避免使用数字，但可用2代替to，用4代替for等，如：go2Jsp。
4.2 文件、包
1) 文件名当与其类严格相同，没个单词的必须首字母大写。
2) 包名一般以项目或模块名命名，少用缩写和长名，一律小写。
3) 基本包：com.sp，所有包、文件都从属于此包。
4) 包名按如下规则组成：
[基本包].[项目名].[模块名].[子模块名]...
如：
com.sp.model
com.sp.dao
5) 不得将类直接定义在基本包下，所有项目中的类、接口等都当定义在各自的项目和模块包中。
4.3 类、接口
所有单词首字母大写。使用能确切反应该类、接口含义、功能等的词。一般采用名词。
接口可带I前缀或able、ible、er等后缀。
4.4 字段
常量
采用完整的英文大写单词，在词与词之间用下划线连接，如：DEFAULT_VALUE
变量和参数
对不易清楚识别出该变量类型的变量应使用类型缩写作其前缀，如字符串使用strXXX,boolean使用isXXX，hasXXX等等。除第一各个单词外其余单词首字母大写。
对私有实例变量可使用_前缀，但在其存取方法中则应该将其前缀去掉。
组件/部件
应采用完整的英文描述符命名组件（接口部件），遵循匈牙利命名法则
如：btnOK，lblName。
集合
一个集合，例如数组和矢量，应采用复数命名来表示队列中存放的对象类型。命名应采用完整的英文描述符，名字中所有非开头的单词的第一个字母应大写，适当使用集合缩写前缀。如：
| Vector vProducts = new Vector(); //产品向量 Array aryUsers = new Array(); //用户列表 |
神秘的数
我们在程序里经常会用到一些量，它是有特定的含义的。例如，现在我们写一个薪金统计程序，公司员工有50人，我们在程序里就会用50这个数去进行各种各样的运算。在这里，50就是"神秘的数"。当别的程序员在程序里看到50这个数，将很难知道它的含义，造成理解上的困难。
在程序里出现"神秘的数"会降低程序的可读性、可维护性和可扩展性，故规定不得出现此类"神秘的数"。避免的方法是把神秘的数定义为一个常量。注意这个常量的命名应该能表达该数的意义，并且应该全部大写，以与对应于变量的标识符区别开来。例如上面50这个数，我们可以定义为一个名为NUM_OF_EMPLOYEES的常量来代替。这样，别的程序员在读程序的时候就可以容易理解了。
其他
命名时应使用复数来表示它们代表多值。如：orderItems。
4.5 方法
方法的命名应采用完整的英文描述符，大小写混合使用：所有中间单词的第一个字母大写。方法名称的第一个单词常常采用一个有强烈动作色彩的动词。
取值类使用get前缀，设值类使用set前缀，判断类使用is(has)前缀。
| 例： getName() setSarry() isLogon() |
方法参数建议顺序：(被操作者，操作内容，操作标志，其他⋯)
| public void replace(String sourceStr, //源字串 String oldStr, //被替换字串 String newStr){ //替换为字串 //Code ***************************** } |
异常
异常类名由表示该异常类型的单词和Exception组成，如ActionException。异常实例一般使用e、ex等，在多个异常时使用该异常名或简写加E，Ex等组成，如：
| SQLEx ActionEx |
4.6 命名约定表
Table7 命名约定表
| 序号 | 操作项 | 命名约定 | 示例 |
| 1 | 参数
| 使用传递值/对象的完整的英文描述符。
| userID
|
| 2 | 字段/属性
| 字段采用完整的英文描述，第一个字母小写，任何中间单词的首字母大写。
| firstName
|
| 3 | 布尔型的获取成员函数
| 所有的布尔型获取函数必须用单词 is（has）做前缀。
| isString() hasMoney()
|
| 4 | 类
| 采用完整的英文描述符，所有单词的第一个字母大写。
| Customer
|
| 5 | 编译单元文件
| 使用类或接口的名字，或者如果文件中除了主类之外还有多个类时，加上前缀 java 来说明它是一个源码文件。
| Customer.java
|
| 6 | 部件/组件
| 使用完整的英文描述来说明组件的用途，将组件类型使用匈牙利命名法则作其前缀。
| btnOK,cboTypeList
|
| 7 | 构造函数
| 使用类名
| Customer()
|
| 8 | 析构函数
| Java 没有析构函数，但一个对象在垃圾收集时，调用成员函数 finalize() 。 | finalize()
|
| 9 | 异常类名
| 由表示该异常类型等的单词和Exception组成
| SQLException ActionException
|
| 10 | 异常实例名
| 通常采用字母 e 、ex表示异常。多个异常时使用异常名或其简写加E、Ex等构成 | e SQLEx
|
| 11 |
静态常量字段（常量）
| 全部采用大写字母，单词之间用下划线分隔。采用静态常量获取成员函数。
| DEFAULT_NAME
|
| 12 | 获取成员函数
| 被访问字段名的前面加上前缀 get。 | getUserName()
|
| 13 | 接口
| 采用完整的英文描述符说明接口封装，所有单词的第一个字母大写。使用I前缀，其后使用able,. ible 或者 er等后缀，但这不是必需的。 | IRunnable IPrompter
|
| 14 | 局部变量
| 采用完整的英文描述符，第一个字母小写，但不要隐藏已有字段。例如，如果有一个字段叫 firstName，不要让一个局部变量叫 firstName。 | strName,totalMoney
|
| 15 | 循环计数器
| 通常采用字母 i，j，k 或者 counter，index | i,j,k,count,index
|
| 16 | 包 | 采用完整的英文描述符，所有单词都小写，多个单词以下划线相连。所有包都属于 | com.sp com.sp.model com.sp.dao.impl |
| 17 | 成员函数
| 采用完整的英文描述说明成员函数功能，第一个单词尽可能采用一个生动的动词，除第一个单词外，每个单词第一个字母小写。 | openFile() addUser()
|
| 18 | 设置成员函数
| 被访问字段名的前面加上前缀 set。 | setName() setPower() |
第5章 声明
5.1 基本原则
声明的基本原则是遵守Java语言规范，并遵从习惯用法。
5.2 包
在导入包时当完全限制代码所使用的类的名字,尽量少用通配符的方式(增加系统的开销)，但导入一些通用包，或用到一个包下大部分类时，则可是使用通配符方式，如：
| import com.catv.quasar.services.Service; import java.util.*; |
同一包中的类导入时当声明在一起，可由编辑器自动完成此功能。
重要的包当添加注释。
5.3 类、接口
类、接口定义语法规范：
| [可见性][('abstract'|'final')] [Class|Interface] class_name [('extends'|'implements')][父类或接口名]{ } 如： public class LoginAction extends BaseAction implemnets ActionListener { } |
5.4 方法
良好的程序设计应该尽可能减小类与类之间耦合，所遵循的经验法则是：尽量限制成员函数的可见性。如果成员函数没必要公有 (public)，就定义为保护 (protected)；没必要保护 (protected)，就定义为私有 (private)。
方法定义语法规范：
| [可见性][('abstract'|'final')] ['synchronized'][返回值类型] method_name(参数列表)[('throws')][异常列表]{ // 功能模块 } 如： public List listAllUsers() throws DAOException{ } |
若有toString(),equals(),hashCode(),colone()等重载自Object的方法，应将其放在类的最后。声明顺序：
1) 构造方法
2) 静态公共方法
3) 静态私有方法
4) 受保护方法
5) 私有方法
6) 继承自Object的方法
5.5 字段
字段定义语法规范：
| [(‘public’|’private’|’protected’)] [(‘final’|’volatile’)][‘static’][‘transient’] data_type field_name [ ‘=’ expression] ‘;’ |
若没有足够理由，不要把实例或类变量声明为公有。公共和保护的可见性应当尽量避免，所有的字段都建议置为私有，由获取和设置成员函数（Getter、Setter）访问。
不允许“隐藏”字段，即给局部变量所取的名字，不可与另一个更大范围内定义的字段的名字相同（或相似）。例如，如果把一个字段叫做 firstName ，就不要再生成一个局部变量叫做 firstName，或者任何易混肴的名字，如 fistName。
数组声明时当将"[]"跟再类型后，而不时字段名后，如：
| Integer[] ai = new Integer (2); //一个整数对象数组，用于... Integer aj[] = new Integer (3); //不要用这种数组声明方式 |
一行代码只声明一个变量，仅将一个变量用于一件事。
声明顺序：
1) 常量
2) 类变量
3) 实例变量
4) 公有字段
5) 受保护字段
6) 私有字段
可以将私有变量声明在类或接口的最后。
注意受保护变量、私有变量、“包”变量间的区别。
5.6 示例
Table8
| //常量--------------------------------------------------- public final static double PI = 3.141592653589793; // -------------------------------------------------类变量 protected static String key = “Love”; // -----------------------------------------------实例变量 //共有字段----------------------------------------------- public String userName = “Tom”; //受保护字段--------------------------------------------- protected float price = 0.0; //友元字段----------------------------------------------- Vector vPorducts = null; //私有字段----------------------------------------------- private int count; //构造方法----------------------------------------------- public Constructor(){ } //公共方法----------------------------------------------- public String getUserName(){ } //友元方法----------------------------------------------- void createProduct(){ } //受保护方法--------------------------------------------- protected void convert(){ } //私有方法----------------------------------------------- private void init(){ } //重载Object方法---------------------------------------- public String toString(){ } //main方法----------------------------------------------- public static void main(String[] args){ } |
第6章 类与接口
6.1 基本原则
类的划分粒度，不可太大，造成过于庞大的单个类，也不可太细，从而使类的继承太深。一般而言，一个类只做一件事；另一个原则是根据每个类的职责进行划分，比如用User来存放用户信息，而用UserDAO来对用户信息进行数据访问操作（比如存取数据库），用UserBroker来封装用户信息的业务操作等等。
多使用设计模式，随时重构。多个类中使用相同方法时将其方法提到一个接口中或使用抽象类，尽量提高重用度。
将不希望再被继承的类声明成final，例如某些实用类，但不要滥用final，否则会对系统的可扩展性造成影响。
将不希望被实例化的类的缺省构造方法声明成private。
6.2 抽象类与接口
一般而言：接口定义行为，而抽象类定义属性和公有行为，注意两者间的取舍，在设计中，可由接口定义公用的行为，由一个抽象类来实现其部分或全部方法，以给子类提供统一的行为定义，可参考Java集合等实现。
多使用接口，尽量做到面向接口的设计，以提高系统的可扩展性。
6.3 继承与组合
尽量使用组合来代替继承，一则可以使类的层次不至于过深，而且会使类与类，包与包之间的耦合度更小，更具可扩展性。
6.4 构造函数和静态工厂方法
当需要使用多个构造函数创建类时，建议使用静态工厂方法替代这些构造方法(参考《EffictiveJava》 Item1)，例如：
| public class User { public User() { super(); //do somethings to create user instance } public static User getInstance(String name,String password) { User u = new User(); u.setName(name); u.setPassword(password); return u; } } |
参看String，Boolean的实现等：String.valueOf(Longl),Boolean.valueOf(String)...
6.5 toString(),equals(),hashCode()...
每个类都应该重载toString()方法，以使该类能输出必要和有用的信息等。
| /** * @see java.lang.Object#toString() */ public String toString() { final StringBuffer sb = new StringBuffer("Actor:["); sb.append("ID = ").append(_id) .append(",Name = ").append(_name) .append(']'); return sb.toString(); } |
若一个类需要重载equals()方法，则必须同时重载hashCode()方法实现方式参考《Effictive Java》Item7,Item8
| /** * @see java.lang.Object#equals(java.lang.Object) */ public boolean equals (Object obj) { //空值 if( null == obj) { return false; } //引用相等 if (obj == this) { return true; } //判断是否为当前类实例 if (!(obj instanceof Actor)) { return false; } //若ID相等则认为该对象相等 return this._id == ((Actor) obj).getId (); } |
| /** * @see java.lang.Object#hashCode() */ public int hashCode () { int result = 17;//init result //String 对象hashCode result = (37 * result) + _name.hashCode (); //数值 result = (37 * result) + (int) (_id ^ (_id >>> 32)); //String 对象hashCode result = (37 * result) + _description.hashCode (); return result; }
|
这些方法的重载实现也可参考如下实现（使用Jakarta commons-lang）;
6.6 Singleton Class
单例类使用如下方式声明，并将其缺省构造方法声明成private：
| public class Singleton{ private static Singleton instance = new Singleton(); // 私有缺省构造方法，避免被其他类实例化 private Singleton() { //do something } public static Singleton getInstance() { if(null == instance) { instance = new Singleton; } return instance; } }//EOC Singleton
|
单例类若需要实现序列化，则必须提供readResolve()方法，以使反序列化出来的类仍然是唯一的实例，参考《Effictive Java》 Item57。
第7章 方法
7.1 基本原则
一个方法只完成一项功能，在定义系统的公用接口方法外的方法应尽可能的缩小其可见性。
避免用一个类是实例去访问其静态变量和方法。
避免在一个较长的方法里提供多个出口：
| //不要使用这钟方式，当处理程序段很长时将很难找到出口点 if(condition) { return A; }else { return B; } //建议使用如下方式 String result = null; if(condition){ result = A; }else{ result = B; } return result; |
7.2 参数和返回值
避免过多的参数列表，尽量控制在5个以内，若需要传递多个参数时，当使用一个容纳这些参数的对象进行传递，以提高程序的可读性和可扩展性。
参数类型和返回值尽量接口化，以屏蔽具体的实现细节，提高系统的可扩展性，例如：
| public void joinGroup(List userList){} public List listAllUsers(){} |
第8章 表达式与语句
8.1 基本原则
表达式和语句当清晰、简洁，易于阅读和理解，避免使用晦涩难懂的语句。
每行至多包含一条执行语句，过长当换行。
避免在构造方法中执行大量耗时的初始化工作，应当将这中工作延迟到被使用时再创建相应资源，如果不可避免，则当使用对象池和Cache等技术提高系统性能。
避免在一个语句中给多个变量赋相同的值。它很难读懂。
不要使用内嵌(embedded)赋值运算符试图提高运行时的效率，这是编译器的工作。
尽量在声明局部变量的同时初始化。唯一不这么做的理由是变量的初始值依赖于某些先前发生的计算。
一般而言，在含有多种运算符的表达式中使用圆括号来避免运算符优先级问题，是个好方法。即使运算符的优先级对你而言可能很清楚，但对其他人未必如此。你不能假设别的程序员和你一样清楚运算符的优先级。
不要为了表现编程技巧而过分使用技巧，简单就好。
8.2 控制语句
判断中如有常量，则应将常量置与判断式的右侧。如：
| if ( true == isAdmin())... if ( null == user)... |
尽量不使用三目条件判断。
所有if语句必须用{}包括起来,即便是只有一句：
| if (true){ //do something...... } if (true) i = 0; //不要使用这种 |
当有多个else分句时当分别注明其条件，注意缩进并对齐，如：
| //先判断i 是否等于1 if (i == 1){//if_1 //..... }//然后判断i == 2 else if (i == 2){ //i == 2说明。。。。。。 j = i; }//如果都不是(i > 2 || i < 1) else{ //说明出错了 //.... }//end if_1 过多的else分句请将其转成switch语句或使用子函数。 |
每当一个case顺着往下执行时(因为没有break语句)，通常应在break语句的位置添加注释。如：
| switch (condition) { case ABC: //statements; //继续下一个CASE case DEF: //statements; break; case XYZ: //statements; break; default: //statements; break; }//end switch |
8.3 循环语句
循环中必须有终止循环的条件或语句，避免死循环。
当在for语句的初始化或更新子句中使用逗号时，避免因使用三个以上变量，而导致复杂度提高。若需要，可以在for循环之前(为初始化子句)或for循环末尾(为更新子句)使用单独的语句。
因为循环条件在每次循环中多会执行一次，故尽量避免在其中调用耗时或费资源的操作，比较一下两种循环的差异：
| //不推荐方式____________________________________________ while(index < products.getCount()){ //每此都会执行一次getCount()方法， //若此方法耗时则会影响执行效率 //而且可能带来同步问题，若有同步需求，请使用同步块或同步方法 } //推荐方式______________________________________________ //将操作结构保存在临时变量里，减少方法调用次数 final int count = products.getCount(); while(index < count) { } |
第9章 错误与异常
9.1 基本原则
通常的思想是只对错误采用异常处理：逻辑和编程错误，设置错误，被破坏的数据，资源耗尽，等等。
通常的法则是系统在正常状态下以及无重载和硬件失效状态下，不应产生任何异常。最小化从一个给定的抽象类中导出的异常的个数。对于经常发生的可预计事件不要采用异常。
不要使用异常实现控制结构。确保状态码有一个正确值。在本地进行安全性检查，而不是让用户去做。若有finally子句，则不要在try块中直接返回，亦不要在finally中直接返回。
9.2 已检查异常与运行时异常
已检查异常必须捕捉并做相应处理，不能将已检查异常抛到系统之外去处理。
对可预见的运行时异常当进行捕捉并处理，比如空指针等。通常，对空指针的判断不是使用捕捉NullPointException的方式，而是在调用该对象之前使用判断语句进行直接判断，如：
| //若不对list是否为null进行检查，则在其为null时会抛出空指针异常 if(null != list && 0 < list.size()) { for(int i = 0; i < list.size(); i++) { } } |
建议使用运行时异常(RuntimeException)代替已检查异常（CheckedException），请参考网络资源以对此两种异常做更深入理解。
9.3 异常的捕捉与处理
捕捉异常是为了处理它，不要捕捉了却什么都不处理而抛弃之，最低限度当向控制台输出当前异常，如果你不想处理它，请将该异常抛给它的调用者，建议对每个捕捉到的异常都调用printStackTrace()输出异常信息，避免因异常的湮没。
多个异常应分别捕捉并处理，避免使用一个单一的catch来处理。如：
| try { //do something }catch(IllegalStateException IllEx) { IllEx.printStackTrace(); //deal with IllEx }catch(SQLException SQLEx) { SQLEx.printStackTrace(); throw SQLEx; //抛给调用者处理 }finally { //释放资源 } |
第10章 测试与Bug跟踪
10.1 基本原则
测试不通过的代码不得提交到SVN库或者发布。
不得隐瞒、忽略、绕过任何Bug，有Bug不一定是你的错，但有了Bug不作为就是你的不对了。
多做测试，测试要完全，尽量将各种可能情况都测试通过，尽量将可能的Bug在开发中捕捉并处理掉。
测试要保证可再测试性。
测试应当对数据库等资源不留或少留痕迹，例如，当测试添加一个用户时，在其成功后当及时从数据库中删除该记录，以避免脏数据的产生（由此衍生的一个经验是将添加、获取、删除一起测试）。
对关键功能必须测试并通过，对辅助功能及非常简单之功能可不做测试。
10.2 测试驱动开发
测试驱动开发可很好的避免Bug的发生，并提升程序的质量，有助于提高个人的编程水平等，因此在开发中当逐步转向有测试驱动的开发，先写测试，再写代码。
具体请参考《测试驱动开发》。
10.3 Junit单元测试
在Java应用中，单元测试使用Junit及其衍生工具。
在TestCase的setUp()中初始化应用，在tearDown()中释放资源。可由一个基础TestCase完成这些任务，其他TestCase继承之。
基于Eclipse的Junit的单元测试使用，请参考《单位测试规范使用手册》。
10.4 自动测试与持续集成
测试应当由系统自动完成并向相应人员发送测试报告。
由持续集成工具来完成测试的自动化。
10.5 Bug跟踪和缺陷处理
当系统出现Bug时当由该Bug的负责人（代码负责人）尽快修改之。Bug的处理根据其优先级高低和级别高低先后处理。Bug级别和优先级别参见《Bugzilla测试使用手册》。
禁止隐瞒Bug。
第11章 性能与安全
11.1 基本原则
性能的提升并不是一蹴而就的，而是由良好的编程积累的，虽然任何良好的习惯和经验所提升的性能都十分有限，甚至微乎其微，但良好的系统性能却是由这些习惯等积累而成，不积细流，无以成江海！
11.2 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 时间。
11.3 集合
避免使用Vector和HashTable等旧的集合实现，这些实现的存在仅是为了与旧的系统兼容，而且由于这些实现是同步的，故而在大量操作时会带来不必要的性能损失。在新的系统设计中不当出现这些实现，使用ArrayList代替Vector，使用HashMap代替HashTable。
若却是需要使用同步集合类，当使用如下方式获得同步集合实例：
| Map map = Collections.synchronizedMap(new HashMap()); |
由于数组、ArrayList与Vector之间的性能差异巨大（具体参见《Java fitball》），故在能使用数组时不要使用ArrayList，尽量避免使用Vector。
11.4 对象
避免在循环中频繁构建和释放对象。
不再使用的对象应及时销毁。
如无必要，不要序列化对象。
11.5 同步
在不需要同步操作时避免使用同步操作类，如能使用ArrayList时不要使用Vector。
尽量少用同步方法，避免使用太多的 synchronized 关键字。
尽量将同步最小化，即将同步作用到最需要的地方，避免大块的同步块或方法等。
11.6 final
将参数或方法声明成final可提高程序响应效率，故此：
注意绝对不要仅因为性能而将类、方法等声明成final，声明成final的类、方法一定要确信不再被继承或重载！
不需要重新赋值的变量（包括类变量、实例变量、局部变量）声明成final
所有方法参数声明成final
私有(private)方法不需要声明成final
若方法确定不会被继承，则声明成final
11.7 垃圾收集和资源释放
不要过分依赖JVM的垃圾收集机制，因为你无法预测和知道JVM在什么时候运行GC。
尽可能早的释放资源，不再使用的资源请立即释放。
可能有异常的操作时必须在try的finally块中释放资源，如数据库连接、IO操作等：
| Connection conn = null; try{ //do something }catch(Exception e) //异常捕捉和处理 { e.printStackTrack(); }finally{ //判断conn等是否为null if(null != conn){ conn.close(); } }//end try...catch...finally |
第12章 其他
12.1 目录结构
目录结构由用AntColony之newapp建立新项目时自动建立，参考结构如下：
| 目 录 | 说明 | ||
|
| 一级目录 | 二级目录 | |
| ProjectName |
|
| 项目目录，当和项目名一致 |
|
| /build |
| 构建目录 |
|
|
| /classes | 类构建目录 |
|
| /src |
| 源码目录 |
|
|
| /com/sp | Java类文件 |
|
|
| /com/../ hibernate | Hibernate映射文件 |
|
|
| /com/../test | 单元测试类文件 |
|
| /config |
| 配置目录 |
|
|
| /app | 应用信息配置 |
|
|
| /log | 日志配置信息 |
|
|
| /web | Web配置信息 |
|
|
| /hibernate | Hibernate配置信息 |
|
|
| /struts | Struts配置信息 |
|
| /metadata |
| 元数据目录 |
|
|
| /db | 数据库脚本 |
|
| /docs |
| 文档目录 |
|
|
| /api | JavaDoc目录 |
|
|
| /j2h | Java2Html目录 |
|
|
| /design | 设计文档目录 |
|
| /lib |
| 库文件目录 |
|
|
| /buildtime | 构建时库目录 |
|
|
| /runtime | 运行时库目录 |
|
| /webapp |
| Web目录 |
|
|
| /module | 模块目录 |
|
|
| /images | 图片目录 |
|
|
| /WEB-INF | WEB-INF目录 |
|
| /log |
| 日志目录 |
|
|
| /buildtime | 构建时日志 |
|
|
| /runtime | 运行时日志 |
|
|
| /test | 测试日志 |
12.2 SVN注释与标记
每次向SVN服务器提交时都必须给出注释，以标明本次提交所作的改动以及目的等。
在开发周期中，除由系统定时给项目打上时间戳标记外，当在各个阶段对项目进行标记，如将第一次在SVN库中建立项目时命名为baseline01，在第4个里程碑后命名为M4。
项目结束时相关代码当即冻结。新阶段时当将相应代码版本提升，如从1.0提升到2.0。
SVN中尽量不放置大容量二进制文件，如某些jar运行库等。
具体参见《SVN手册》。
第13章 附录
13.1 SVN标识符
| 标识符 | 说明 |
| $Id$
| 标识，包括文件名，版本，提交时间，提交者等信息 $Id: HibernateFilter.java,v 1.1 2003/11/17 13:20:07 l_Jemmy Exp $
|
| $Author$
| 最后提交者 $Author: l_Jemmy $
|
| $Reversion$
| 当前版本（服务器版本） $Revision: 1.1 $
|
| $Date$
| 最后一次提交时间 $Date: 2003/11/17 13:20:07 $
|
其他标识符及详细说明请参见SVN文档。
13.2 注释模板
以下注释均针对Eclipse和WSAD，其他开发工具可相应调整之。在Eclipse中，输入SVN标识符必须以双$开头，否则Eclipse会认为其为Eclipse内置参数而报错。
文件头注释：
| /* ============================================= * $$Id$$ * Created [${date} ${time}] by ${user} * ============================================= * * ${project_name}$ * * ============================================= * The 800so Software License v1.0 content. * （详细内容参见13.4 版权声明模板） * ============================================= */ |
类注释：
| /** * <p>${file_name}</p> * * @author $$Author$$ * @version $$Revision$$ $$Date$$ */ |
1) ${date} 创建日期
2) ${time} 创建时间
3) ${user} 创建者
4) ${project_name} 项目名称
5) ${file_name} 文件名
请在您的编辑器中使用相应标识符替代，若无，则可使用相应SVN标识符替代，但当使用SVN标识符替代后，当创建文件后当删除相应标记，避免因SVN的自动更新标识符功能而导致创建信息的丢失等。
13.3 常用缩写简表
| 缩写 | 全字 | 说明 |
| app | application | 应用程序 |
| ctx | context | 上下文信息 |
| mgr | manager | 管理者，经理 |
| conn | connection | 连接（数据库连接） |
| sys | system | 系统 |
13.4 版权声明模板
| /* ================================================================== * $$Id$$ * * Created: [${date} ${time}] by ${user} * ================================================================== * * ${project_name} * * ================================================================== * 800so Apache Style License v1.0 * * Copyright (c) 800so Framework, 2002-2004 * ================================================================== * * Redistribution and use in source and binary forms, with or without * modification, are permitted provided that the following conditions * are met: * * 1. Redistributions of source code must retain the above copyright * notice, this list of conditions, and the following disclaimer. * * 2. Redistributions in binary form must reproduce the above * copyright notice, this list of conditions, and the disclaimer * that follows these conditions in the documentation and/or other * materials provided with the distribution. * * 3. The name "800so" must not be used to endorse or promote * products derived from this software without prior written * permission.For written permission, please contact * xiaosong@u88.cn. * * 4. Products derived from this software may not be called "800so", * nor may "800so" appear in their name, without prior written * permission from xiao song(xiaosong@u88.cn). * * 5. Redistributions of any form whatsoever must retain the * following acknowledgment: * "This product includes software developed by 800so Framework." * * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE * DISCLAIMED. IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE FOR ANY * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING * NEGLIGENCE OR OTHERWISE) ARISING * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE * POSSIBILITY OF SUCH DAMAGE. * * For more information on 800so, please * see <http://www.800so.cn>. * * ==============================================================*/ |
13.5 示例代码
| /* ============================================= * $Id: DAOFactory.java,v 1.4 2003/10/20 14:18:44 l_Zhy Exp $ * Created on [2003-10-8 22:48:12] by l_Jemmy * ============================================= * The 800so Software License v1.0 * * Content... * =============================================== */ package org.catv.quasar.dao; import org.apache.commons.collections.FastHashMap; import org.apache.commons.logging.Log; import org.apache.commons.logging.LogFactory; import com.catv.quasar.config.ApplicationConfiguration; import com.catv.quasar.util.StringUtil; /** * <p>DAO工厂类。</p> * * @author $Author: l_zhy $ * @version $Revision: 1.4 $ $Date: 2003/10/20 14:18:44 $ */ public class DAOFactory { //~ Static fields/initializers =================================== /**DAOFactory singleton instance.*/ private static DAOFactory instance = new DAOFactory(); //~ Instance fields ============================================== /** Logging */ private Log log = LogFactory.getLog (this.getClass ()); /**DAO pool.*/ protected FastHashMap daos = new FastHashMap(); /**DAO configuration.*/ protected DAOConfig daoConfig = null; //~ Constructors ================================================ /** * Default Construtor. */ private DAOFactory () { super(); daoConfig =ApplicationConfiguration.getInstance().getDAOConfiguration(); } //~ Methods ===================================================== /** * 取DAO工厂,Singleton模式以确保系统中只有一个DAOFactory实例。 * * @return DAO工厂实例 */ public static synchronized DAOFactory getInstance () { if (null == instance) { instance = new DAOFactory(); } return instance; } /** * 从DAO池中取对应KEY的DAO实例。 * 若该实例未存在，则从DAO配置中取该DAO的Mapping，并从中取该DAO的实现类的类名， * 初始化之并将其置入池中缓存。 * * @param key DAO Key，默认为该类（接口）全限定名 * @return DAO实例 * @throws DAOException 若 */ public synchronized DAO findDAOByKey (final String key) throws DAOException { //get dao instance from dao pool DAO daoInstance = (DAO) daos.get (key); //get dao mapping final DAOMapping daoMapping = daoConfig.findDAOMapping (key); //if null or different type bewteen the current dao and it's mapping if ((null == daoInstance) || !daoInstance.validateType (daoMapping.getCurrentType ())) { try { final String daoImplClass = daoMapping.findDAOImplClass (daoMapping.getCurrentType ()); if (StringUtil.isNullOrEmpty (daoImplClass)) { throw new DAOException( "Not found DAO implement class of:[" + daoMapping + "]"); } //new instance Class clazz = Class.forName (daoImplClass); daoInstance = (DAO) clazz.newInstance (); //set current type daoInstance.setCurrentType (daoMapping.getCurrentType ()); //add to dao pool daos.setFast (false); daos.put (key, daoInstance); daos.setFast (true); if (log.isDebugEnabled ()) { log.debug ("A DAO instance created:[" + key + "]"); } } catch (ClassNotFoundException e) { log.error ("ClassNotFoundException:" + e.getMessage()); throw new DAOException(e); } catch (InstantiationException e) { log.error ("InstantiationException:" + e.getMessage()); throw new DAOException(e); } catch (IllegalAccessException e) { log.error ("IllegalAccessException:" + e.getMessage()); throw new DAOException(e); }//end try...catch... }//end if...daoInstance is null? return daoInstance; }//end findDAOByKey
}//EOC DAOFactory
|
136
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
