AgileJava Code Standard - AgileJava

该文档记录 AgileJava 项目的开发规则，编码规则以及相关规则，请大家能够遵守规则，来把我们的开源做的很好。

Java Class 编码规范

我们使用 JDK 1.5 作为我们的基本开发环境，所有代码将使用 JDK 1.5 的新特性，如：范型，Annotation 等；
我们的 Java 文件的编码规范遵循 Sun 的 Code Conventions for the Java Programming Language；
代码格式化规范遵守 Eclipse 的默认格式化规范，在代码编写完成时，请按 Ctrl + Shift + F 把你的代码格式化一下，同样 InteliJ IDEA 的默认规范也是适合的，默认格式化快捷键 Ctrl + Alt + L；
package 以 org.agilejava 开头，后面跟上项目的名称，再后面名字根据自己的设计而定，名称要符合 Java 规范，例如:org.agilejava.icustomer.util；
请使用 import java.util.Vector 而不要使用 import java.util.* ，代码写完后请使用 IDE 的优化 Import 的快捷键来优化一下 import 的 Class，Eclipse 下是 Ctrl + Shift + O，IDEA 下是 Ctrl + Alt + O；
我们统一使用中文作为注释语言；
所有对类文件的注包含对该类文件用途的说明，并注明 @author；
类中方法要包含有该方法功能和使用的说明，方法命名要遵守 Java 规范；
方法中对复杂逻辑要注释；
不要在循环体内声明变量；
当一个字符串常量在两个及以上的地方被用到，必须将其定义为常量 Field，以避免hardcode；
方法不宜太大, 可以将部分共用代码提取出来, 建议不超过50行, 抽出来的方法作用域要有限定, 一般为private；
公用的message放在自己项目一个基类中(org.agilejava.icustomer.commons.Constants)，禁止hardcode message；
用 log 代替 System.out.println() 和 e.printTraceStack()
log的级别为DEBUG < INFO < WARN < ERROR < FATAL
当级别为 DEBUG 级时，使用if(log.isDebugEnabled())判断是否需要Log
Log中的信息要简洁并有意义；
判断 String 是否为空时, 使用StringUtils.isEmpty()，判断不为空时使用 StringUtils.isNotEmpty()；
用 "abc".equals(itemName) 代替 itemName. equals ("abc")；
获取日期：本项目中使用 "yyyy-MM-dd" 作为日期的标准格式，定义时使用 Constants 中的相应 Field 作为Pattern，例如：Constants.DATE_FORMAT_XXX
取当前 Date : DateUtil.getSystemDate();
取当前 Timestamp : DateUtil.getSystemTimestamp();
格式化日期：String : DateUtil.parseDate(Date, String(Pattern));
从 String 转换日期：DateUtil.toDate(String strDateTime, String, dateTimeFormat);
注：DateUtil 指的是：org.agilejava.framework.util.DateUtil；

文件夹结构

基本文件夹结构：

项目构建管理办法

Ant 的 build.xml 和 build.properties 文件放在 ProjectRoot 下，项目要保证在刚刚 check out 出来，不使用任何 IDE 仅仅使用 Ant 的情况下能够 build 出来。
不要 check in 和 IDE 相关的文件，比如 Eclipse 的 .project 文件。

Jar 包管理办法

在使用 Maven 之前，我们暂时采取各个项目持有自己的 jar 文件的方案，在 Web 项目中，我们把 jar 文件放在 WebRoot/WEB-INF/lib 下；
jar 包命名按照 jarname-version.jar 的形式保存，以明确所用 jar 包的版本，如：acegi-security-1.0.2.jar，commons-el-1.0.jar；

Hibernate 3 持久层使用方法

我们使用 Hibernate 3 作为我们的数据持久化方案；
Hibernate 中包含 Criteria， HQL 和 SQL 三种查询方式；
我们开发中应尽量避免直接使用 SQL 作为查询；
我们优先使用 Criteria 作为查询方式，通常可以解决 90% 的问题，当发现有问题不能用 Criteria 查询时，首先检查你的对象关联配置是否正确；
少数情况实在无法使用 Criteria 进行查询，可考虑使用 HQL，同时将该问题提出来，让大家共同分析并找寻不能使用的原因；
TODO

Spring 配置及对象管理办法

我们使用 Spring 2.0 作为我们的中间层(Service 层)及事务处理方案；
TODO

AgileJava Framework 使用方法

我们所有 AgileJava 的项目将基于 AgileJava Framework 开发，该 Framework 提供了项目所需的一些基类和工具类；
AgileJava Framework 的 package 为： org.agilejava.framework；
Domain Object，VO 或 POJO 等这些直接表示系统业务对象的 JavaBean 均继承自 org.agilejava.framework.base.domain.BaseVO；
所有的 DAO 均继承自 org.agilejava.framework.base.persistence.BaseDAO 以便使用其中的功能，具体请参考其中的方法注释；
所有的 Service 均继承自 org.agilejava.framework.base.service.BaseService；
JSF 的普通不需要分页的 Backing Bean 均继承自 org.agilejava.framework.jsf.base.BaseBackingBean，需要用到分页的均继承自 org.agilejava.framework.jsf.base.BasePagedBackingBean，该类只对一个 DataModel 中的数据进行分页。
TODO