2) hilo
通过hi/lo 算法实现的主键生成机制，需要额外的数据库表保存主
键生成历史状态。

3) seqhilo
与hilo 类似，通过hi/lo 算法实现的主键生成机制，只是主键历史
状态保存在Sequence中，适用于支持Sequence的数据库，如Oracle。

4) increment
主键按数值顺序递增。此方式的实现机制为在当前应用实例中维持
一个变量，以保存着当前的最大值，之后每次需要生成主键的时候
将此值加1作为主键。
这种方式可能产生的问题是：如果当前有多个实例访问同一个数据
库，那么由于各个实例各自维护主键状态，不同实例可能生成同样
的主键，从而造成主键重复异常。因此，如果同一数据库有多个实
例访问，此方式必须避免使用。

5) identity
采用数据库提供的主键生成机制。如DB2、SQL Server、MySQL
中的主键生成机制。

6) sequence
采用数据库提供的sequence 机制生成主键。如Oralce 中的
Sequence。

7) native
由Hibernate根据底层数据库自行判断采用identity、hilo、sequence
其中一种作为主键生成方式。

8) uuid.hex
由Hibernate基于128 位唯一值产生算法生成16 进制数值（编码后
以长度32 的字符串表示）作为主键。

9) uuid.string
与uuid.hex 类似，只是生成的主键未进行编码（长度16）。在某些
数据库中可能出现问题（如PostgreSQL）。

10) foreign
使用外部表的字段作为主键。
一般而言，利用uuid.hex方式生成主键将提供最好的性能和数据库平台适
应性。

另外由于常用的数据库，如Oracle、DB2、SQLServer、MySql 等，都提
供了易用的主键生成机制（Auto-Increase 字段或者Sequence）。我们可以在数
据库提供的主键生成机制上，采用generator-class=native的主键生成方式。
不过值得注意的是，一些数据库提供的主键生成机制在效率上未必最佳，
大量并发insert数据时可能会引起表之间的互锁。
数据库提供的主键生成机制，往往是通过在一个内部表中保存当前主键状
态（如对于自增型主键而言，此内部表中就维护着当前的最大值和递增量），
之后每次插入数据会读取这个最大值，然后加上递增量作为新记录的主键，之
后再把这个新的最大值更新回内部表中，这样，一次Insert操作可能导致数据
库内部多次表读写操作，同时伴随的还有数据的加锁解锁操作，这对性能产生
了较大影响。
因此，对于并发Insert要求较高的系统，推荐采用uuid.hex 作为主键生成
机制。

SpringSide代码规范

前言

    本文档反映的是SpringSide 团队的编码规范，同时推荐所有使用SpringSide框架的开发人员遵循。

    本文档基本遵循Sun's Coding Conventions，补充了其中没有说明或者有所改动的地方。

版权声明   

    本规范由springside团队维护，相关评论与意见请发至springside@gmail.com，转载请注明出处。

规范等级说明

• 级别I:   默认级别，要求所有项目中的所有成员遵守。
• 级别II:  建议所有项目中的所有成员遵守。
• 级别III: 鼓励各个项目根据实际情况执行。

1.格式与命名规范(Formating and Naming Conventions)

1.1  缩进

  使用Tab缩进，而不是空格键--将缩进2，4，8字符的选择权留给阅读者。

1.2 换行

   每行120字符--因为已是1024*768的年代。

   if,for,while语句只有单句时，如果该句可能引起阅读混淆，需要用" {"和"}"括起来，否则可以省略。

//错误，需要使用花括号{}括起来

if (condition)

if(condition) doSomething();

else

doSomething();

1.3 命名规则 

• 不允许使用汉语拼音命名 
• 遇到缩写如XML时，仅首字母大写，即loadXmlDocument()而不是loadXMLDocument()
• Package名必须全部小写，尽量使用单个单词
• Interface名可以是一个名词或形容词(加上'able','ible', or 'er'后缀)，如Runnable，Accessible。
  为了基于接口编程，不采用首字母为I或加上IF后缀的命名方式，如IBookDao,BookDaoIF。
• 页面部件名建议命名为：btnOK、lblName或okBtn、nameLbl。(II)
  其中btn、lbl缩写代表按钮(Button)、标签(Label)。
• 局部变量及输入参数不要与类成员变量同名(get/set方法与构造函数除外)

1.4 声明

• 修饰符应该按照如下顺序排列：public, protected, private, abstract, static, final, transient, volatile, synchronized, native, strictfp。
• 类与接口的声明顺序(可用Eclipse的source->sort members功能自动排列): 
  1. 静态成员变量 / Static Fields
  2. 静态初始化块 / Static Initializers
  3. 成员变量 / Fields
  4. 初始化块 / Initializers
  5. 构造器 / Constructors
  6. 静态成员方法 / Static Methods
  7. 成员方法 / Methods
  8. 重载自Object的方法如toString(), hashCode() 和main方法
  9. 类型(内部类) / Types(Inner Classes)

     同等的类型，按public, protected, private的顺序排列。

2.注释规范(Document Convertions)

2.1 注释类型

2.1.1 JavaDoc注释

  略。

2.1.2 失效代码注释

  由/*...*/界定，标准的C-Style的注释。专用于注释已失效的代码。

/*

 * Comment out the code

 * String s = "hello";

* System.out.println(s);

 */

2.1.3 代码细节注释

  由//界定，专用于注释代码细节，即使有多行注释也仍然使用//，以便与用/**/注释的失效代码分开

  除了私有变量外，不推荐使用行末注释。

class MyClass {



private int myField; // An end-line comment.



public void myMethod {



//a very very long

//comment.

if (condition1) {

//condition1 comment

...

} else {

//elses condition comment

...

}

}

}

2.2 注释的格式

• 注释中的第一个句子要以（英文）句号、问号或者感叹号结束。Javadoc生成工具会将注释中的第一个句子放在方法汇总表和索引中。
• 为了在JavaDoc和IDE中能快速链接跳转到相关联的类与方法，尽量多的使用@see xxx.MyClass，@see xx.MyClass#find(String)。
• Class必须以@author 作者名声明作者，不需要声明@version与@date，由版本管理系统保留此信息。(II)
• 如果注释中有超过一个段落，用

  分隔。(II)

• 示例代码以包裹。(II)
• 标识(java keyword, class/method/field/argument名，Constants) 以包裹。(II)
• 标识在第一次出现时以{@linkxxx.Myclass}注解以便JavaDoc与IDE中可以链接。(II)

2.3 注释的内容

2.3.1 可精简的注释内容

    注释中的每一个单词都要有其不可缺少的意义，注释里不写"@param name -名字"这样的废话。
    如果该注释是废话，连同标签删掉它，而不是自动生成一堆空的标签，如空的@param name，空的@return。

2.3.2 推荐的注释内容

• 对于API函数如果存在契约，必须写明它的前置条件(precondition)，后置条件(postcondition)，及不变式(invariant)。(II)
• 对于调用复杂的API尽量提供代码示例。(II)
• 对于已知的Bug需要声明。(II)
• 在本函数中抛出的unchecked exception尽量用@throws说明。(II)

2.3.3 Null规约

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

/**

 * 获取对象.

 *

 * @ return the object to found or null if not found.

 */

Object get(Integer id){

...

}

2.3.4 特殊代码注释

• 代码质量不好但能正常运行，或者还没有实现的代码用//TODO: 或 //XXX:声明 
• 存在错误隐患的代码用//FIXME:声明

3.编程规范(Programming Conventions)

3.1基本规范

1. 当面对不可知的调用者时，方法需要对输入参数进行校验，如不符合抛出IllegalArgumentException，建议使用Spring的Assert系列函数。 
2. 隐藏工具类的构造器，确保只有static方法和变量的类不能被构造实例。
3. 变量，参数和返回值定义尽量基于接口而不是具体实现类，如Map map = new HashMap();
4. 代码中不能使用System.out.println()，e.printStackTrace()，必须使用logger打印信息。

3.2 异常处理

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

3.3 代码度量

3.3.1 耦合度度量

• DAC度量值不要不大于7 ( III )
  解释：DAC(Data Abstraction Coupling)数据抽象耦合度是描述对象之间的耦合度的一种代码度量。DAC度量值表示一个类中有实例化的其它类的个数。
• CFO度量值不要不大于20 ( III )
  解释：CFO(Class Fan Out)类扇出是描述类之间的耦合度的一种代码度量。CFO度量值表示一个类依赖的其他类的个数。

3.3.2 方法度量

• 方法（构造器）参数在5个以内 ( II )
  太多的方法（构造器）参数影响代码可读性。考虑用值对象代替这些参数或重新设计。
• 方法长度150行以内 ( II )
• CC 度量值不大于10(III )
  解释：CC(CyclomaticComplexity)圈复杂度指一个方法的独立路径的数量，可以用一个方法内if,while,do,for,catch,switch,case,?:语句与&&,||操作符的总个数来度量。
• NPath度量值不大于200 ( III )
  解释：NPath度量值表示一个方法内可能的执行路径的条数。

3.3.3 其他度量

• 布尔表达式中的布尔运算符(&&,||)的个数不超过3个(III) 
• if语句的嵌套层数3层以内(II)
• 文件长度2000行以内(II)
• 匿名内部类20行以内 ( II )
  太长的匿名内部类影响代码可读性，建议重构为命名的（普通）内部类。

3.4 JDK5.0

1. 重载方法必须使用@Override，可避免父类方法改变时导致重载函数失效。
2. 不需要关心的warning信息用@SuppressWarnings("unused"), @SuppressWarnings("unchecked"), @SuppressWarnings("serial") 注释。

4.自动代码检查

   使用Eclipse与 Inellij IDEA的代码校验功能已经排除了很多问题。

   再配合使用Checkstyle，PMD，FindBugs三重检查，总共五层的校验涵盖了Java编码大部分的Guide Line。

   如果要求不苛刻，可以只使用Eclipse或IDEA 搭配 Checkstyle的两重保湿效果。

1. Eclipse：在Windows->Preferences->Java-Compiler->Errors/Warnings中，按本文档将一些原来Ignore的规则打开。
   也可以将springside团队预设在/tools/codereviewer/eclipse.check.prefs的内容拷贝到项目的.setting/org.eclipse.jdt.core.prefs 文件中。
2. IDEA：在Setting->Errors中设定规则，调用Analyzer->Inspece Code进行校验。
3. CheckStyle：安装CheckStyle的Eclipse插件，在Windows->Preferences->CheckStyle导入springside团队预设在/tools/codereviewer/springside_check.xml的规则。
4. PMD：安装PMD的Eclipse插件，Windows->Preferences->PMD清除原来所有规则，导入springside团队预设在/tools/codereviewer/springside_pmd.xml的规则。
5. FindBugs：安装FindBugs的Eclipse插件，在项目属性->FindBugs中，取消下列警告MS/EI/EI2/ ， SnVI/SE/WS/RS ，ST/NP/UwF/SS/UuF|UrF|SIC。