編碼規範

前言

本文檔反映的是SpringSide 團隊的編碼規範，同時推薦所有使用SpringSide框架的開發人員遵循。

本文檔基本遵循Sun's Coding Conventions，補充了其中沒有說明或者有所改動的地方。

版權聲明

本規範由springside團隊維護，相關評論與意見請發至[email protected]，轉載請註明出處。

規範等級說明

• 級別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 {

privateint 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 nullif 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