SpringSide的代码规范

ozy518

前言   
    本文档反映的是SpringSide 团队的编码规范，同时推荐所有使用SpringSide框架的开发人员遵循。
    本文档基本遵循
Sun's Coding Conventions
[img]mk:@MSITStore:D:\oksonic.chm::/630_files/linkext7[1].gif[/img]

，补充了其中没有说明或者有所改动的地方。
    本文档随SpringSide的开发而不断更新，最新版本请访问SpringSide Wiki：
   
   
http://wiki.springside.org.cn/display/springside/Coding+Standards
版权声明   
    本规范由
springside团队
[img]mk:@MSITStore:D:\oksonic.chm::/630_files/linkext7[1].gif[/img]

维护，相关评论与意见请发至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功能自动排列):  
  
• 静态成员变量 / Static Fields
  
• 静态初始化块 / Static Initializers
  
• 成员变量 / Fields
  
• 初始化块 / Initializers
  
• 构造器 / Constructors
  
• 静态成员方法 / Static Methods
  
• 成员方法 / Methods
  
• 重载自Object的方法如toString(), hashCode() 和main方法
  
• 类型(内部类) / 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基本规范

当面对不可知的调用者时，方法需要对输入参数进行校验，如不符合抛出IllegalArgumentException，建议使用Spring的Assert系列函数。  

隐藏工具类的构造器，确保只有static方法和变量的类不能被构造

变量，参数和返回值定义尽量基于接口而不是具体实现类，如Map map = new HashMap();

代码中不能使用System.out.println()，e.printStackTrace()，必须使用logger打印信息。
3.2 异常处理

重新抛出的异常必须保留原来的异常，即throw new NewException("message",e); 而不能写成throw new NewException("message")。

在所有异常被捕获且没有重新抛出的地方必须写日志。  

如果属于正常异常的空异常处理块必须注释说明原因，否则不允许空的catch块。

框架尽量捕获低级异常，并封装成高级异常重新抛出，隐藏低级异常的细节。(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

重载方法必须使用@Override，可避免父类方法改变时导致重载函数失效。

不需要关心的warning报告用@SuppressWarnings("unused"), @SuppressWarnings("unchecked"),@SuppressWarnings("serial") 注释。
4.自动代码检查
   使用
Eclipse


  与
Inellij IDEA


 的代码校验已经可以排除很多问题。
   再配合使用
Checkstyle


 ，
PMD


 ，
FindBugs


 三重检查，共五层的校验涵盖了大部分的Guide Line。
   如果代码要求不苛刻，可以仅使用Eclipse 或 IDEA 搭配 Checkstyle的两重保湿效果。

Eclipse：在Windows->Preferences->Java-Compiler->Errors/Warnings中，按本文档的规则将一些原来Ignore的规则打开。

IDEA：在Setting->Errors中设定规则，调用Analyzer->Inspece Code进行校验。

CheckStyle：安装
CheckStyle的Eclipse插件
[img]mk:@MSITStore:D:\oksonic.chm::/630_files/linkext7[1].gif[/img]

，在Windows->Preferences->CheckStyle导入springside团队预设在/tools/codereviewer/springside_check.xml的规则

PMD：安装
PMD的Eclipse插件
[img]mk:@MSITStore:D:\oksonic.chm::/630_files/linkext7[1].gif[/img]

，Windows->Preferences->PMD清除原来所有规则，导入springside团队预设在/tools/codereviewer/springside_pmd.xml的规则。

FindBugs：安装
FindBugs的Eclipse插件
[img]mk:@MSITStore:D:\oksonic.chm::/630_files/linkext7[1].gif[/img]

，在项目属性->FindBugs中，取消下列警告MS/EI/EI2/ ， SnVI/SE/WS/RS ，ST/NP/UwF/SS/UuF|UrF|SIC  
5.参考资料

Sun's Coding Conventions
[img]mk:@MSITStore:D:\oksonic.chm::/630_files/linkext7[1].gif[/img]

Sun MicroSystem；

The Elements of Java Style
[img]mk:@MSITStore:D:\oksonic.chm::/630_files/linkext7[1].gif[/img]

  Scott W. Ambler 等著；

代码检测工具的规则：
checkstyle
[img]mk:@MSITStore:D:\oksonic.chm::/630_files/linkext7[1].gif[/img]

，
pmd
[img]mk:@MSITStore:D:\oksonic.chm::/630_files/linkext7[1].gif[/img]

，
findbugs
[img]mk:@MSITStore:D:\oksonic.chm::/630_files/linkext7[1].gif[/img]



本文来自ChinaUnix博客，如果查看原文请点：http://blog.chinaunix.net/u1/39124/showart_322121.html