空間站

前言

    本文檔反映的是SpringSide 團隊的編碼規(guī)范，同時推薦所有使用SpringSide框架的開發(fā)人員遵循。

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

版權(quán)聲明   

    本規(guī)范由springside團隊維護(hù)，相關(guān)評論與意見請發(fā)至springside@gmail.com，轉(zhuǎn)載請注明出處。

規(guī)范等級說明

• 級別I:   默認(rèn)級別，要求所有項目中的所有成員遵守。
• 級別II:  建議所有項目中的所有成員遵守。
• 級別III: 鼓勵各個項目根據(jù)實際情況執(zhí)行。

1.格式與命名規(guī)范(Formating and Naming Conventions)

1.1  縮進(jìn)

  使用Tab縮進(jìn)，而不是空格鍵--將縮進(jìn)2，4，8字符的選擇權(quán)留給閱讀者。

1.2 換行

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

   if,for,while語句只有單句時，如果該句可能引起閱讀混淆，需要用" {"和"}"括起來，否則可以省略。

//錯誤，需要使用花括號{}括起來
if (condition)
if(condition) doSomething();
else
doSomething();

1.3 命名規(guī)則 

• 不允許使用漢語拼音命名 
• 遇到縮寫如XML時，僅首字母大寫，即loadXmlDocument()而不是loadXMLDocument()
• Package名必須全部小寫，盡量使用單個單詞
• Interface名可以是一個名詞或形容詞(加上'able','ible', or 'er'后綴)，如Runnable，Accessible。
  為了基于接口編程，不采用首字母為I或加上IF后綴的命名方式，如IBookDao,BookDaoIF。
• 頁面部件名建議命名為：btnOK、lblName或okBtn、nameLbl。(II)
  其中btn、lbl縮寫代表按鈕(Button)、標(biāo)簽(Label)。
• 局部變量及輸入?yún)?shù)不要與類成員變量同名(get/set方法與構(gòu)造函數(shù)除外)

1.4 聲明

• 修飾符應(yīng)該按照如下順序排列：public, protected, private, abstract, static, final, transient, volatile, synchronized, native, strictfp。
• 類與接口的聲明順序(可用Eclipse的source->sort members功能自動排列): 
  1. 靜態(tài)成員變量 / Static Fields
  2. 靜態(tài)初始化塊 / Static Initializers
  3. 成員變量 / Fields
  4. 初始化塊 / Initializers
  5. 構(gòu)造器 / Constructors
  6. 靜態(tài)成員方法 / Static Methods
  7. 成員方法 / Methods
  8. 重載自O(shè)bject的方法如toString(), hashCode() 和main方法
  9. 類型(內(nèi)部類) / Types(Inner Classes)

     同等的類型，按public, protected, private的順序排列。

2.注釋規(guī)范(Document Convertions)

2.1 注釋類型

2.1.1 JavaDoc注釋

  略。

2.1.2 失效代碼注釋

  由/*...*/界定，標(biāo)準(zhǔn)的C-Style的注釋。專用于注釋已失效的代碼。

/*
 * Comment out the code
 * String s = "hello";
* System.out.println(s);
 */

2.1.3 代碼細(xì)節(jié)注釋

  由//界定，專用于注釋代碼細(xì)節(jié)，即使有多行注釋也仍然使用//，以便與用/**/注釋的失效代碼分開

  除了私有變量外，不推薦使用行末注釋。

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 注釋的格式

• 注釋中的第一個句子要以（英文）句號、問號或者感嘆號結(jié)束。Javadoc生成工具會將注釋中的第一個句子放在方法匯總表和索引中。
• 為了在JavaDoc和IDE中能快速鏈接跳轉(zhuǎn)到相關(guān)聯(lián)的類與方法，盡量多的使用@see xxx.MyClass，@see xx.MyClass#find(String)。
• Class必須以@author 作者名聲明作者，不需要聲明@version與@date，由版本管理系統(tǒng)保留此信息。(II)
• 如果注釋中有超過一個段落，用<p>分隔。(II)
• 示例代碼以<pre></pre>包裹。(II)
• 標(biāo)識(java keyword, class/method/field/argument名，Constants) 以<code></code>包裹。(II)
• 標(biāo)識在第一次出現(xiàn)時以{@linkxxx.Myclass}注解以便JavaDoc與IDE中可以鏈接。(II)

2.3 注釋的內(nèi)容

2.3.1 可精簡的注釋內(nèi)容

    注釋中的每一個單詞都要有其不可缺少的意義，注釋里不寫"@param name -名字"這樣的廢話。
    如果該注釋是廢話，連同標(biāo)簽刪掉它，而不是自動生成一堆空的標(biāo)簽，如空的@param name，空的@return。

2.3.2 推薦的注釋內(nèi)容

• 對于API函數(shù)如果存在契約，必須寫明它的前置條件(precondition)，后置條件(postcondition)，及不變式(invariant)。(II)
• 對于調(diào)用復(fù)雜的API盡量提供代碼示例。(II)
• 對于已知的Bug需要聲明。(II)
• 在本函數(shù)中拋出的unchecked exception盡量用@throws說明。(II)

2.3.3 Null規(guī)約

   如果方法允許Null作為參數(shù)，或者允許返回值為Null，必須在JavaDoc中說明。
   如果沒有說明，方法的調(diào)用者不允許使用Null作為參數(shù)，并認(rèn)為返回值是Null Safe的。

/**
 * 獲取對象.
 *
 * @ return the object to found or null if not found.
 */
Object get(Integer id){
...
}

2.3.4 特殊代碼注釋

• 代碼質(zhì)量不好但能正常運行，或者還沒有實現(xiàn)的代碼用//TODO: 或 //XXX:聲明 
• 存在錯誤隱患的代碼用//FIXME:聲明

3.編程規(guī)范(Programming Conventions)

3.1基本規(guī)范

1. 當(dāng)面對不可知的調(diào)用者時，方法需要對輸入?yún)?shù)進(jìn)行校驗，如不符合拋出IllegalArgumentException，建議使用Spring的Assert系列函數(shù)。 
2. 隱藏工具類的構(gòu)造器，確保只有static方法和變量的類不能被構(gòu)造實例。
3. 變量，參數(shù)和返回值定義盡量基于接口而不是具體實現(xiàn)類，如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. 框架盡量捕獲低級異常，并封裝成高級異常重新拋出，隱藏低級異常的細(xì)節(jié)。(III)

3.3 代碼度量

3.3.1 耦合度度量

• DAC度量值不要不大于7 ( III )
  解釋：DAC(Data Abstraction Coupling)數(shù)據(jù)抽象耦合度是描述對象之間的耦合度的一種代碼度量。DAC度量值表示一個類中有實例化的其它類的個數(shù)。
• CFO度量值不要不大于20 ( III )
  解釋：CFO(Class Fan Out)類扇出是描述類之間的耦合度的一種代碼度量。CFO度量值表示一個類依賴的其他類的個數(shù)。

3.3.2 方法度量

• 方法（構(gòu)造器）參數(shù)在5個以內(nèi) ( II )
  太多的方法（構(gòu)造器）參數(shù)影響代碼可讀性。考慮用值對象代替這些參數(shù)或重新設(shè)計。
• 方法長度150行以內(nèi) ( II )
• CC 度量值不大于10(III )
  解釋：CC(CyclomaticComplexity)圈復(fù)雜度指一個方法的獨立路徑的數(shù)量，可以用一個方法內(nèi)if,while,do,for,catch,switch,case,?:語句與&&,||操作符的總個數(shù)來度量。
• NPath度量值不大于200 ( III )
  解釋：NPath度量值表示一個方法內(nèi)可能的執(zhí)行路徑的條數(shù)。

3.3.3 其他度量

• 布爾表達(dá)式中的布爾運算符(&&,||)的個數(shù)不超過3個(III) 
• if語句的嵌套層數(shù)3層以內(nèi)(II)
• 文件長度2000行以內(nèi)(II)
• 匿名內(nèi)部類20行以內(nèi) ( II )
  太長的匿名內(nèi)部類影響代碼可讀性，建議重構(gòu)為命名的（普通）內(nèi)部類。

3.4 JDK5.0

1. 重載方法必須使用@Override，可避免父類方法改變時導(dǎo)致重載函數(shù)失效。
2. 不需要關(guān)心的warning信息用@SuppressWarnings("unused"), @SuppressWarnings("unchecked"), @SuppressWarnings("serial") 注釋。

4.自動代碼檢查

   使用Eclipse與 Inellij IDEA的代碼校驗功能已經(jīng)排除了很多問題。

   再配合使用Checkstyle，PMD，FindBugs三重檢查，總共五層的校驗涵蓋了Java編碼大部分的Guide Line。

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

1. Eclipse：在Windows->Preferences->Java-Compiler->Errors/Warnings中，按本文檔將一些原來Ignore的規(guī)則打開。
   也可以將springside團隊預(yù)設(shè)在/tools/codereviewer/eclipse.check.prefs的內(nèi)容拷貝到項目的.setting/org.eclipse.jdt.core.prefs 文件中。
2. IDEA：在Setting->Errors中設(shè)定規(guī)則，調(diào)用Analyzer->Inspece Code進(jìn)行校驗。
3. CheckStyle：安裝CheckStyle的Eclipse插件，在Windows->Preferences->CheckStyle導(dǎo)入springside團隊預(yù)設(shè)在/tools/codereviewer/springside_check.xml的規(guī)則。
4. PMD：安裝PMD的Eclipse插件，Windows->Preferences->PMD清除原來所有規(guī)則，導(dǎo)入springside團隊預(yù)設(shè)在/tools/codereviewer/springside_pmd.xml的規(guī)則。
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. 代碼檢測工具的規(guī)則： checkstyle，pmd ，findbugs