空間站

前言

    本文檔反映的是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)
• 如果注釋中有超過一個段落，用<p>分隔。(II)
• 示例代碼以<pre></pre>包裹。(II)
• 標識(java keyword, class/method/field/argument名，Constants) 以<code></code>包裹。(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。

5.參考資料

1. Sun's Coding Conventions Sun MicroSystem；
2. The Elements of Java Style  Scott W. Ambler 等著；
3. 代碼檢測工具的規則： checkstyle，pmd ，findbugs