軟件工程項目組代碼規範

1 代碼格式

• 全部的縮進爲4個空格，使用VS.NET的默認設置。
• 在代碼中垂直對齊左括號和右括號。

　　　　if(x==0)

     　　{

          　　Response.Write("用戶編號必須輸入！");

     　　}

        不容許如下狀況：

　　　　if(x==0) {

              Response.Write("用戶編號必須輸入！");

     　　}

　　　或者：

　　　　if(x==0){ Response.Write("用戶編號必須輸入！");}

• 每一行上放置的語句避免超過一條。
• 在大多數運算符以前和以後使用空格，這樣作時不會改變代碼的意圖卻可使代碼容易閱讀。

　　例：

         int j = i + k; 

　　而不該寫爲

    　　int j=i+k;

• 代碼整理可使用快捷鍵Ctrl+K+F

2 命名指南

2.1 大寫樣式

　　使用下面的三種大寫標識符約定。

　　Pascal 大小寫

　　將標識符的首字母和後面鏈接的每一個單詞的首字母都大寫。能夠對三字符或更多字符的標識符使用 Pascal 大小寫。例如：

　　BackColor

　　Camel 大小寫

　　標識符的首字母小寫，而每一個後面鏈接的單詞的首字母都大寫。例如：

　　backColor

　　大寫

　　標識符中的全部字母都大寫。僅對於由兩個或者更少字母組成的標識符使用該約定。例如：

　　System.IO

　　System.Web.UI

　　可能還必須大寫標識符以維持與現有非託管符號方案的兼容性，在該方案中全部大寫字母常常用於枚舉和常數值。通常狀況下，在使用它們的程序集以外這些字符應當是不可見的。

　　下表彙總了大寫規則，並提供了不一樣類型的標識符的示例。

 

標識符	大小寫	示例
類	Pascal	AppDomain
枚舉類型	Pascal	ErrorLevel
枚舉值	Pascal	FatalError
事件	Pascal	ValueChange
異常類	Pascal	WebException 注意 老是以 Exception 後綴結尾。
只讀的靜態字段	Pascal	RedValue
接口	Pascal	IDisposable 注意 老是以 I 前綴開始。
方法	Pascal	ToString
命名空間	Pascal	System.Drawing
參數	Camel	typeName
屬性	Pascal	BackColor
受保護的實例字段	Camel	redValue 注意 不多使用。屬性優於使用受保護的實例字段。
公共實例字段	Pascal	RedValue 注意 不多使用。屬性優於使用公共實例字段。

2.2 區分大小寫

　　爲了不混淆和保證跨語言交互操做，請遵循有關區分大小寫的使用的下列規則：

• 不要使用要求區分大小寫的名稱。對於區分大小寫和不區分大小寫的語言，組件都必須徹底可使用。不區分大小寫的語言沒法區分同一上下文中僅大小寫不一樣的兩個名稱。所以，在建立的組件或類中必須避免這種狀況。
• 不要建立僅是名稱大小寫有區別的兩個命名空間。例如，不區分大小寫的語言沒法區分如下兩個命名空間聲明。

　　namespace ee.cummings;

　　namespace Ee.Cummings;

•  不要建立具備僅是大小寫有區別的參數名稱的函數。下面的示例是不正確的。

　　void MyFunction(string a, string A)

•  不要建立具備僅是大小寫有區別的類型名稱的命名空間。在下面的示例中，Point p 和 POINT p 是不適當的類型名稱，緣由是它們僅是大小寫有區別。

　　System.Windows.Forms.Point p

　　System.Windows.Forms.POINT p

• 不要建立具備僅是大小寫有區別的屬性名稱的類型。在下面的示例中，int Color 和 int COLOR 是不適當的屬性名稱，緣由是它們僅是大小寫有區別。

　　int Color {get, set}

　　int COLOR {get, set}

• 不要建立具備僅是大小寫有區別的方法名稱的類型。在下面的示例中，calculate 和 Calculate 是不適當的方法名稱，緣由是它們僅是大小寫有區別。

　　void calculate()

　　void Calculate()

2.3 縮寫

　　爲了不混淆和保證跨語言交互操做，請遵循有關區縮寫的使用的下列規則：

• 不要將縮寫或縮略形式用做標識符名稱的組成部分。例如，使用 GetWindow，而不要使用 GetWin。
• 不要使用計算機領域中未被廣泛接受的縮寫。
• 在適當的時候，使用衆所周知的縮寫替換冗長的詞組名稱。例如，用 UI 做爲 User Interface 的縮寫，用 OLAP 做爲 On-line Analytical Processing 的縮寫。
• 在使用縮寫時，對於超過兩個字符長度的縮寫請使用 Pascal 大小寫或 Camel 大小寫。例如，使用 HtmlButton 或 HTMLButton。可是，應當大寫僅有兩個字符的縮寫，如，System.IO，而不是 System.Io。
• 不要在標識符或參數名稱中使用縮寫。若是必須使用縮寫，對於由多於兩個字符所組成的縮寫請使用 Camel 大小寫，雖然這和單詞的標準縮寫相沖突。
• 特別針對程序設計中組件設計內容較多，對於組件縮寫命名遵循如下規則：

組件類型	縮寫	例子
Label	Lbl	lblNote
TextBox	Txt	txtName
Button	Btn	btnOK
ImageButton	Ib	ibOK
LinkButton	Lb	lbJump
HyperLink	Hl	hlJump
DropDownList	Ddl	ddlList
CheckBox	Cb	cbChoice
CheckBoxList	Cbl	cblGroup
RadioButton	Rb	rbChoice
RadioButtonList	Rbl	rblGroup
Image	Img	imgBeauty
Panel	Pnl	pnlTree
TreeView	Tv	tvUnit
WebComTable	Wct	wctBasic
ImageDateTimeInput	Dti	dtiStart
ComboBox	Cb	cbList
MyImageButton	Mib	mibOK
WebComm.TreeView	Tv	tvUnit
PageBar	Pb	pbMaster

2.4 命名空間的命名

　　命名命名空間時的通常性規則是使用公司名稱，後跟技術名稱和可選的功能與設計，以下所示。

　　CompanyName.TechnologyName[.Feature][.Design]

　　例如：

　　Microsoft.Media

　　Microsoft.Media.Design

　　給命名空間名稱加上公司名稱或者其餘知名商標的前綴能夠避免兩個已經發布的命名空間名稱相同的可能性。例如，Microsoft.Office 是由 Microsoft 提供的 Office Automation Classes 的一個適當的前綴。

　　在第二級分層名稱上使用穩定的、公認的技術名稱。將組織層次架構用做命名空間層次架構的基礎。命名一個命名空間，該命名空間包含爲具備 .Design 後綴的基命名空間提供設計時功能的類型。例如，System.Windows.Forms.Design 命名空間包含用於設計基於 System.Windows.Forms 的應用程序的設計器和相關的類。

　　嵌套的命名空間應當在包含它的命名空間中的類型上有依賴項。例如，System.Web.UI.Design 中的類依賴於 System.Web.UI 中的類。可是，System.Web.UI 中的類不依賴於 System.UI.Design 中的類。

　　應當對命名空間使用 Pascal 大小寫，並用句點分隔邏輯組件，如 Microsoft.Office.PowerPoint 中所示。若是您的商標使用非傳統的大小寫，請遵循您的商標所定義的大小寫，即便它與規定的 Pascal 大小寫相背離。例如，命名空間 NeXT.WebObjects 和 ee.cummings 闡釋了對於 Pascal 大小寫規則的適當背離。

　　若是在語義上適當，使用複數命名空間名稱。例如，使用 System.Collections而不是 System.Collection。此規則的例外是商標名稱和縮寫。例如，使用 System.IO而不是 System.IOs。

　　不要爲命名空間和類使用相同的名稱。例如，不要既提供 Debug 命名空間也提供 Debug 類。

　　最後，請注意命名空間名稱沒必要非得與程序集名稱類似。例如，若是命名程序集 MyCompany.MyTechnology.dll，它沒有必要非得包含 MyCompany.MyTechnology 命名空間。

2.5 類命名

　　如下規則概述命名類：

• 使用名詞或名詞短語命名類。
• 使用 Pascal 大小寫。
• 少用縮寫。
• 不要使用類型前綴，如在類名稱上對類使用 C 前綴。例如，使用類名稱 FileStream，而不是 CFileStream。
• 不要使用下劃線字符 (_)。
• 有時候須要提供以字母 I 開始的類名稱，雖然該類不是接口。只要 I 是做爲類名稱組成部分的整個單詞的第一個字母，這即是適當的。例如，類名稱 IdentityStore 是適當的。
• 在適當的地方，使用複合單詞命名派生的類。派生類名稱的第二個部分應當是基類的名稱。例如，ApplicationException 對於從名爲 Exception 的類派生的類是適當的名稱，緣由是 ApplicationException 是一種 Exception。請在應用該規則時進行合理的判斷。例如，Button 對於從 Control 派生的類是適當的名稱。儘管按鈕是一種控件，可是將 Control 做爲類名稱的一部分將使名稱沒必要要地加長。

　　下面是正確命名的類的示例。

　　[Visual Basic]

　　Public Class FileStream

　　Public Class Button

　　Public Class String

　　[C#]

　　public class FileStream

　　public class Button

　　public class String

2.6 類成員變量命名

       類成員變量加 m_ 前綴，如： int m_ContentLength。

2.7 接口命名

　　如下規則概述接口的命名：

• 用名詞或名詞短語，或者描述行爲的形容詞命名接口。例如，接口名稱 IComponent 使用描述性名詞。接口名稱 ICustomAttributeProvider 使用名詞短語。名稱 IPersistable 使用形容詞。
• 使用 Pascal 大小寫。
• 少用縮寫。
• 給接口名稱加上字母 I 前綴，以指示該類型爲接口。
• 在定義類/接口對（其中類是接口的標準實現）時使用類似的名稱。兩個名稱的區別應該只是接口名稱上有字母 I 前綴。
• 不要使用下劃線字符 (_)。

　　如下是正確命名的接口的示例。

　　[Visual Basic]

　　Public Interface IServiceProvider

　　Public Interface IFormatable

　　[C#]

　　public interface IServiceProvider

　　public interface IFormatable

　　如下代碼示例闡釋如何定義 IComponent 接口及其標準實現 Component 類。

　　[Visual Basic]

　　Public Interface IComponent

  　　 ' Implementation code goes here.

　　End Interface

 

　　Public Class Component

   　　Implements IComponent

   　　' Implementation code goes here.

　　End Class

　　[C#]

　　public interface IComponent

　　{

 

　　}

　　public class Component: IComponent

　　{

  　　// Implementation code goes here.

　　}

2.8 枚舉類型命名

　　枚舉 (Enum) 值類型從 Enum 類繼承。如下規則概述枚舉的命名指南：

• 對於 Enum 類型和值名稱使用 Pascal 大小寫。
• 少用縮寫。
• 不要在 Enum 類型名稱上使用 Enum 後綴。
• 對大多數 Enum 類型使用單數名稱，可是對做爲位域的 Enum 類型使用複數名稱。
• 老是將 FlagsAttribute 添加到位域 Enum 類型。

2.9 靜態字段命名

　　如下規則概述靜態字段的命名：

• 使用名詞、名詞短語或者名詞的縮寫命名靜態字段。
• 使用 Pascal 大小寫。
• 對靜態字段名稱使用匈牙利語表示法前綴。
• 建議儘量使用靜態屬性而不是公共靜態字段。

2.10 參數命名

　　如下規則概述參數的命名：

• 使用描述性參數名稱。參數名稱應當具備足夠的描述性，以便參數的名稱及其類型可用於在大多數狀況下肯定它的含義。
• 對參數名稱使用 Camel 大小寫。
• 使用描述參數的含義的名稱，而不要使用描述參數的類型的名稱。開發工具將提供有關參數的類型的有意義的信息。所以，經過描述意義，能夠更好地使用參數的名稱。少用基於類型的參數名稱，僅在適合使用它們的地方使用它們。
• 不要使用保留的參數。保留的參數是專用參數，若是須要，能夠在將來的版本中公開它們。相反，若是在類庫的將來版本中須要更多的數據，請爲方法添加新的重載。
• 不要給參數名稱加匈牙利語類型表示法的前綴。

　　如下是正確命名的參數的示例。

　　[Visual Basic]

　　GetType(typeName As String)As Type

　　Format(format As String, object [] args)As String

　　[C#]

　　Type GetType(string typeName)

　　string Format(string format, args() As object)

2.11 方法命名

　　如下規則概述方法的命名：

• 使用動詞或動詞短語命名方法。
• 使用 Pascal 大小寫。

　　如下是正確命名的方法的實例。

　　RemoveAll()

　　GetCharArray()

　　Invoke()

2.12 屬性命名

　　如下規則概述屬性的命名：

• 使用名詞或名詞短語命名屬性。
• 使用 Pascal 大小寫。
• 不要使用匈牙利語表示法。
• 考慮用與屬性的基礎類型相同的名稱建立屬性。例如，若是聲明名爲 Color 的屬性，則屬性的類型一樣應該是 Color。請參閱本主題中後面的示例。

　　如下代碼示例闡釋正確的屬性命名。

　　[Visual Basic]

　　Public Class SampleClass

   　　Public Property BackColor As Color

      　　' Code for Get and Set accessors goes here.

   　　End Property

　　End Class

　　[C#]

　　public class SampleClass

　　{

   　　public Color BackColor

   　　{

     　　 // Code for Get and Set accessors goes here.

   　　}

　　}

　　如下代碼示例闡釋提供其名稱與類型相同的屬性。

　　[Visual Basic]

　　Public Enum Color

  　　 ' Insert code for Enum here.

　　End Enum

　　Public Class Control

  　　 Public Property Color As Color

      　　Get

        　　 ' Insert code here.

     　　 End Get

      　　Set

         　　' Insert code here.

     　　 End Set

   　　End Property

　　End Class

　　[C#]

　　public enum Color

　　{

 　　  // Insert code for Enum here.

　　}

　　public class Control

　　{

   　　public Color Color

   　　{

     　　 get {// Insert code here.}

     　　 set {// Insert code here.}

  　　 }

　　}

　　如下代碼示例不正確，緣由是 Color 屬性是 Integer 類型的。

　　[Visual Basic]

　　Public Enum Color

  　　 ' Insert code for Enum here.

　　End Enum

　　Public Class Control

   　　Public Property Color As Integer

     　　 Get

      　　   ' Insert code here.

     　　 End Get

    　　  Set

    　　     ' Insert code here.

     　　 End Set

   　　End Property

　　End Class

　　[C#]

　　public enum Color {// Insert code for Enum here.}

　　public class Control

　　{

   　　public int Color

   　　{

     　　 get {// Insert code here.}

     　　 set {// Insert code here.} 

   　　}

　　}

　　在不正確的示例中，不可能引用 Color 枚舉的成員。Color.Xxx 將被解釋爲訪問一個成員，該成員首先獲取 Color 屬性（在 Visual Basic 中爲 Integer 類型，在 C# 中爲 int 類型）的值，而後再訪問該值的某個成員（該成員必須是 System.Int32 的實例成員）。

2.13事件命名

　　如下規則概述事件的命名：

• 對事件處理程序名稱使用 EventHandler 後綴。
• 指定兩個名爲 sender 和 e 的參數。sender 參數表示引起事件的對象。sender 參數始終是 object 類型的，即便在可使用更爲特定的類型時也如此。與事件相關聯的狀態封裝在名爲 e 的事件類的實例中。對 e 參數類型使用適當而特定的事件類。
• 用 EventArgs 後綴命名事件參數類。
• 考慮用動詞命名事件。
• 使用動名詞（動詞的「ing」形式）建立表示事件前的概念的事件名稱，用過去式表示事件後。例如，能夠取消的 Close 事件應當具備 Closing 事件和 Closed 事件。不要使用 BeforeXxx/AfterXxx 命名模式。
• 不要在類型的事件聲明上使用前綴或者後綴。例如，使用 Close，而不要使用 OnClose。
• 一般狀況下，對於能夠在派生類中重寫的事件，應在類型上提供一個受保護的方法（稱爲 OnXxx）。此方法只應具備事件參數 e，由於發送方老是類型的實例。

　　如下示例闡釋具備適當名稱和參數的事件處理程序。

　　public delegate void MouseEventHandler(object sender, MouseEventArgs e); [Visual Basic]

　　Public Delegate Sub MouseEventHandler(sender As Object, e As MouseEventArgs)

　　闡釋正確命名的事件參數類。

　　[Visual Basic]

　　Public Class MouseEventArgs

   　　Inherits EventArgs

   　　Dim x As Integer

   　　Dim y As Integer

 

   　　Public Sub New MouseEventArgs(x As Integer, y As Integer)

     　　 me.x = x

     　　 me.y = y

   　　End Sub

     

  　　Public Property X As Integer

     　　 Get

        　　 Return x

     　　 End Get

  　　 End Property

     

   　　Public Property Y As Integer

      　　Get

        　　 Return y

     　　 End Get

  　　 End Property

　　End Class

　　[C#]

　　public class MouseEventArgs : EventArgs

　　{

   　　int x;

   　　int y;

   　　public MouseEventArgs(int x, int y)

    　　  { this.x = x; this.y = y; }

   　　public int X { get { return x; } }

   　　public int Y { get { return y; } }

　　}

3    註釋（Comment）規範

　　註釋規範包括：模塊（類）註釋規範、類的屬性、方法註釋規範、代碼間註釋

3.1  模塊（類）註釋規範

　　模塊開始必須以如下形式書寫模塊註釋：

　　　 ///<summary>

         ///模塊編號：<模塊編號，能夠引用系統設計中的模塊編號>

         ///做用：<對此類的描述，能夠引用系統設計中的描述>

         ///做者：做者中文名

         ///編寫日期：<模塊建立日期，格式：YYYY-MM-DD>

         ///</summary>

　　若是模塊有修改，則每次修改必須添加如下注釋：

         ///<summary>

         ///Log編號：<Log編號,從1開始一次增長>

         ///修改描述：<對此修改的描述>

         ///做者：修改者中文名

         ///修改日期：<模塊修改日期，格式：YYYY-MM-DD>

         ///</summary>

 3.2 類屬性註釋規範

　　在類的屬性必須以如下格式編寫屬性註釋：

         /// <summary>

         ///屬性說明

　　   /// </summary>

3.3 方法註釋規範

　　在類的方法聲明前必須以如下格式編寫註釋

         /// <summary>

         /// 說明：<對該方法的說明>

         /// </summary>

         /// <param name="<參數名稱>"><參數說明></param>

　　   /// <param name="<參數名稱>"><參數說明></param>

         /// <returns>

         ///<對方法返回值的說明，該說明必須明確說明返回的值表明什麼含義>

         /// </returns>

3.4 代碼間註釋規範

　　代碼間註釋分爲單行註釋和多行註釋：

       單行註釋：

　　　　//<單行註釋>

       多行註釋：

         /*多行註釋1

          多行註釋2

          多行註釋3*/

　　代碼中遇到語句塊時必須添加註釋（if,for,foreach,……）,添加的註釋必須可以說明此語句塊的做用和實現手段（所用算法等等）。

4 異常處理

　　異常的思想是隻對錯誤採用異常處理：邏輯和編程錯誤，設置錯誤，被破壞的數據，資源耗盡，等等。一般的法則是系統在正常狀態下以及無重載和硬件失效狀態下，不該產生任何異常。

• 異常處理時能夠採用適當的日誌機制來報告異常，包括異常發生的時刻；
• 通常狀況下不要使用異常實現來控制程序流程結構；
• 使用異常而不要用錯誤代碼來報告錯誤；
• 要經過拋出異常的方式來報告操做失敗；
• 若是成員沒法成功地完成它應該作的任務，那麼應該拋出異常；

4.1 異常類型選擇規範

• 優先考慮使用System命名空間中已有的異常，而不是本身建立新的異常類型；
• 要使用最合理，最具針對性的異常。例如，對參數爲空，應拋出 System.ArgutmentNullException，而不是System.ArgutmentException

4.2 異常處理規範

• 不是百分之百肯定的狀況，不要吞掉異常；
• 建議捕獲特定類型的異常，若是理解該異常在具體環境當中產生的緣由；
• 不要捕獲不該該捕獲的異常，一般應該容許異常沿着調用棧傳遞；
• 進行清理工做時要用try-finally，避免使用try-catch；
• 要在捕獲並從新拋出異常時使用空的throw語句，這是保持調用棧的最好方法