SpringSide的代碼規(guī)范

前言???

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

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

????本文檔隨SpringSide的開發(fā)而不斷更新，最新版本請?jiān)L問SpringSide Wiki：
????
????http://wiki.springside.org.cn/display/springside/Coding+Standards版權(quán)聲明???

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

規(guī)范等級說明

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

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

1.1??縮進(jìn)

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

1.2 換行

?? 每行120字符--因?yàn)橐咽?024*768的年代。

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

1.3?命名規(guī)則?

• 不允許使用漢語拼音命名?
• 遇到縮寫如XML時(shí)，僅首字母大寫，即loadXmlDocument()而不是loadXMLDocument()
• Package名必須全部小寫，盡量使用單個(gè)單詞
• Interface名可以是一個(gè)名詞或形容詞(加上'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功能自動(dòng)排列):?
  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的注釋。專用于注釋已失效的代碼。

?

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

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

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

?

2.2?注釋的格式

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

2.3?注釋的內(nèi)容

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

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

?

2.3.4 特殊代碼注釋

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

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

3.1基本規(guī)范

1. 當(dāng)面對不可知的調(diào)用者時(shí)，方法需要對輸入?yún)?shù)進(jìn)行校驗(yàn)，如不符合拋出IllegalArgumentException，建議使用Spring的Assert系列函數(shù)。?
2. 隱藏工具類的構(gòu)造器，確保只有static方法和變量的類不能被構(gòu)造
3. 變量，參數(shù)和返回值定義盡量基于接口而不是具體實(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度量值表示一個(gè)類中有實(shí)例化的其它類的個(gè)數(shù)。
• CFO度量值不要不大于20 ( III )
  解釋：CFO(Class Fan Out)類扇出是描述類之間的耦合度的一種代碼度量。CFO度量值表示一個(gè)類依賴的其他類的個(gè)數(shù)。

3.3.2 方法度量

方法（構(gòu)造器）參數(shù)在5個(gè)以內(nèi) ( II )
????太多的方法（構(gòu)造器）參數(shù)影響代碼可讀性。考慮用值對象代替這些參數(shù)或重新設(shè)計(jì)。

方法長度150行以內(nèi) ( II )

CC?度量值不大于10(III )
??? 解釋：CC(CyclomaticComplexity)圈復(fù)雜度指一個(gè)方法的獨(dú)立路徑的數(shù)量，可以用一個(gè)方法內(nèi)if,while,do,for,catch,switch,case,?:語句與&&,||操作符的總個(gè)數(shù)來度量。

NPath度量值不大于200 ( III )
??? 解釋：NPath度量值表示一個(gè)方法內(nèi)可能的執(zhí)行路徑的條數(shù)。?

3.3.3 其他度量

• 布爾表達(dá)式中的布爾運(yùn)算符(&&,||)的個(gè)數(shù)不超過3個(gè)(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，可避免父類方法改變時(shí)導(dǎo)致重載函數(shù)失效。
2. 不需要關(guān)心的warning報(bào)告用@SuppressWarnings("unused"), @SuppressWarnings("unchecked"),@SuppressWarnings("serial") 注釋。

4.自動(dòng)代碼檢查

?? 使用Eclipse? 與 Inellij IDEA?的代碼校驗(yàn)已經(jīng)可以排除很多問題。

?? 再配合使用Checkstyle?，PMD?，FindBugs?三重檢查，共五層的校驗(yàn)涵蓋了大部分的Guide Line。

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

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