前言???

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

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

????本文檔隨SpringSide的開發而不斷更新，最新版本請訪問SpringSide Wiki：
????
????http://wiki.springside.org.cn/display/springside/Coding+Standards版權聲明???

??? 本規范由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?三重檢查，共五層的校驗涵蓋了大部分的Guide Line。

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

    1. Eclipse：在Windows->Preferences->Java-Compiler->Errors/Warnings中，按本文檔的規則將一些原來Ignore的規則打開。
    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 ConventionsSun MicroSystem；
    2. The Elements of Java Style? Scott W. Ambler?等著；
    3. 代碼檢測工具的規則： checkstyle，pmd ，findbugs