C#代碼開發規範

 Wrod下載

 

 

 

 

 

C#代碼開發規範

 

 

文件狀態： [√] 草稿 [  ] 正式 [  ] 修改	文件標識：
	當前版本：	1.1
	做    者：	Empty
	聯繫電話：
	最後更新：	2014-04-07

 

 

版本記錄

 

日期	版本號	做者	說明
2014-4-2	1.0	Empty	建立
2014-4-7	1.1	Empty	添加前言、註釋規範與編碼規範

 

 

 

目    錄

 

1.      前言... 4

1.1        編寫目的... 4

1.2        適用範圍... 4

1.3        基本要求... 4

2.      命名規範... 4

2.1        字母大小寫約定... 4

2.1.1         說明... 4

2.1.2         Pascal風格... 4

2.1.3         Camel風格... 5

2.2        標識符的大小寫規則... 5

2.3        通用命名約定... 5

2.3.1         選擇名稱... 5

2.3.2         字母縮寫詞... 6

2.4        命名空間命名... 6

2.5        類、結構和接口命名... 6

2.6        邏輯層類命名... 6

2.7        文件夾命名... 7

3.      註釋規範... 7

3.1        模塊（類）註釋規範... 7

3.2        類屬性註釋規範... 7

3.3        方法註釋規範... 7

3.4        代碼間註釋規範... 8

4.      編碼規範... 9

 

1.   前言

1.1   編寫目的

爲了保證編寫出的程序都符合相同的規範，保證一致性、統一性而創建的程序編碼規範。

 

編碼規範對於程序員而言尤其重要，有如下幾個緣由：

1) 一個軟件的生命週期中，80%的花費在於維護。

2) 幾乎沒有任何一個軟件，在其整個生命週期中，均由最初的開發人員來維護。

3) 編碼規範能夠改善軟件的可讀性，可讓程序員儘快而完全地理解新的代碼 。

每一個軟件開發人員都必須遵照統一的編碼規範。

1.2   適用範圍

本規範適用於《從零開始編寫本身的C# 框架》的開發。

1.3   基本要求

儘可能使代碼簡單直白。

2.   命名規範

2.1   字母大小寫約定

2.1.1     說明

表達清晰的命名規範是程序規劃的核心，若是規範的命名能清晰的表達出相應的功能，就可讓人「望文知意」，提升開發效率和系統的可維護性。反之，若是命名不能表達其含義，例如「aaa」、「bbb ()」，那麼將拔苗助長。

2.1.2     Pascal風格

包含一到多個單詞，每個單詞第一個字母大寫，其他字母均小寫。例如：HelloWorld、SetName等。

2.1.3     Camel風格

包含一到多個單詞，第一個單詞首字母小寫，其他單詞首字母大寫。例如：name、productId等。

 

2.2   標識符的大小寫規則

1)     除了參數與變量外，全部命名空間名稱、類、函數、接口、屬性等名稱的命名，使用 Pascal 風格。

2)     參數與變量的命名，使用Camel風格。

2.3   通用命名約定

約定的是如何選擇最適當的名稱，這些準則適用於全部標識符命名。

2.3.1     選擇名稱

1)    請選擇易讀的英文名稱

例如，英文 Order的意思爲規則、次序、訂購等，若是用在排序列中就不是很合適，用來表示訂單則更具可讀性。

可讀性比詳細描述更重要，好比表示座標名稱ScreenX就比ScreenHorizontally 更具可讀性。

2)    除下劃線外，不要使用連字符或任何其餘非字母數字字符

在數據庫表字段名稱設計時，與其餘表字段有關聯時，適當的使用表名+下橫線+字段名，能夠更清晰的表現出該字段與關聯表對應字段的關係。

好比產品分類表ProductClass有字段Id與Name，那麼產品表綁定這兩個字段的名稱可命名爲ProductClass_Id與ProductClass_Name，這樣在查看產品表時就能夠清晰的知道這兩個字段與分類表的關係。

3)    避免使用與經常使用編程語言的關鍵字衝突的標識符

4)    變量和方法參數使用Camel 風格

例如：

string productName = "";

int number=0;

string sqlString="";

double averageScore=0.0;

Users users=new Users();

Users model=new Users();

Users userModel=new Users();

const string const_String = "";（不一樣公司有不一樣的約定，具體根據本身公司狀況設置而定）

 

      Private string GetProductName(int id)

{

           return "";

}

5)    不要使用成員屬性做爲成員變量的前綴（其餘變量命名也同樣）

例如： 不要像Users m_users;這樣定義成員變量，可使用第4點的設置。

2.3.2     字母縮寫詞

1)    一般，不該使用縮寫

2)    除非這種縮寫已普遍接受，又或者團隊當中你們都承認一種縮寫

例如，使用 OnButtonClick，若是團隊中廣泛承認OnBtnClick這種寫法也是能夠的。

2.4   命名空間命名

命名空間命名採用Pascal風格，取名的通常規則以下。

CompanyName. ProjectName （公司名稱.項目名稱）

例如：

Microsoft.Office

須要用複數時，請使用複數。

例如，使用System.Collections而不是System.Collection。

須要縮寫時，不須要加複數。

例如：使用System.IO而不是System.IOs。

2.5   類、結構和接口命名

1)    按照 Pascal 大小寫格式，使用名詞或名詞短語爲類、接口和值類型命名

2)    接口命名以字母 I 爲前綴

例如：IComponent

3)    派生類的末尾使用基類名稱

例如，從 Stream 繼承的 Framework 類型以 Stream 結尾，從 Exception 繼承的類型以 Exception 結尾。

2.6   邏輯層類命名

按照 Pascal 大小寫格式，使用名詞或名詞短語命名，並加上後綴Logic

2.7   文件夾命名

文件夾以功能模塊名稱，按照 Pascal 大小寫格式命名。

好比後端管理功能以及權限相關功能，所有放到Systems文件夾裏。

3.   註釋規範

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>

/// <returns>

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

/// </returns>

3.4   代碼間註釋規範

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

單行註釋：

//<單行註釋>

多行註釋：

     /*多行註釋1

     多行註釋2

     多行註釋3*/

代碼行數太多而不容易區分時註釋：

         /******************************************

      *   代碼塊功能名稱

          ******************************************/

//<單行註釋>

         或

/*多行註釋1

     多行註釋2*/

或者也可使用下面方法：

/********* 代碼塊功能名稱開始 ************/

//<單行註釋>

//<單行註釋>

/********* 代碼塊功能名稱結束 ************/

 

註釋說明

A.     代碼中遇到語句塊時必須添加註釋（if,for,foreach,……）,添加的註釋必須可以說明此語句塊的做用和實現手段（所用算法等等）。 對一個數值變量採用不是0,-1等的數值初始化，給出選擇該值的理由。

B.     儘可能多點註釋，就算能一目瞭然的命名最好也順便寫一寫註釋，方便之後接收的人能更容易理解程序（方便不太懂英文的程序員）。

C.     若是由於某種緣由使用了複雜艱澀的原理，爲程序配備良好的文檔和更多的註釋。

4.   編碼規範

1）縮進和間隔：縮進用TAB，不用 SPACES。

2）註釋需和代碼對齊。多使用#regedit和#endregion代碼塊。

3）在代碼中垂直對齊左括號和右括號。

if (x == 0)

{

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

}

    不容許如下狀況：

if(x == 0) {

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

}

或者：

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

4）適當的增長空行，來增長代碼的可讀性。

在下列狀況下應該有兩行空行：

     同一文件的不一樣部分之間；

     在類，接口以及彼此之間；

在下列狀況之間應該有一行空行：

     方法之間；

     局部變量和它後邊的語句之間；

     方法內的功能邏輯部分之間；

5）避免使用大文件。若是一個文件裏的代碼超過300～400行，必須考慮將代碼分開到不一樣類中。固然模板生成類與邏輯層類除外。

6）避免寫太長的方法。一個典型的方法代碼在1～25行之間。若是一個方法發代碼超過25行，應該考慮將其分解爲不一樣的方法。

7）爲了防止在閱讀代碼時不得不滾動源代碼編輯器，每行代碼或註釋在1024*768的顯示頻率下不得超過一顯示屏

8）在大多數運算符以前和以後使用空格，這樣作時不會改變代碼的意圖卻可使代碼容易閱讀。

例：

int j = i + k;  

而不該寫爲

int j=i+k;

括號和它裏面的字符之間不該該出現空格。括號應該和它前邊的關鍵詞留有空格。

例：

while (true)

{

 

};

可是方法名和左括號之間不該該有空格。

參數之間的逗號後應該加一空格。

例：

method1(int i1, int i2)

for語句裏的表達式之間加一空格。

例：

for(expr1; expr2; expr3)

強制類型轉換時，在類型和變量之間加一空格。

例：

(int) i ;

9）全部可供用戶輸入的字段值，必須需忽略先後空白後(不包含密碼)；在對字段值進行有效性驗證。對提交進數據庫的內容必須進行SQL注入過濾與XSS過濾。

10）一個方法只完成一個任務。不要把多個任務組合到一個方法中，即便那些任務很是小。

11）避免使用不少成員變量，聲明局部變量，並傳遞給方法。

12）不要在方法間共享成員變量，若是在幾個方法間共享一個成員變量，那就很難知道是哪一個方法在何時修改了它的值。

13）不在代碼中使用具體的路徑和驅動器名，使用相對路徑，並使路徑可編程。永遠別設想你的代碼是在「C:」盤運行。你不會知道，一些用戶在網絡或「Z:」盤運行程序。

14）應用程序啓動時做些「自檢」並確保所需文件和附件在指定的位置。

若是須要的配置文件找不到，應用程序需能本身建立使用默認值的一份。若是在配置文件中發現錯誤值，應用程序要拋出錯誤，給出提示消息告訴用戶正確值。

15）出現任何問題給用戶一個友好的提示，錯誤消息需能幫助用戶解決問題。

永遠別用像「應用程序出錯」，「發現一個錯誤」等錯誤消息。而應給出像「更新數據庫失敗，請確保登錄id和密碼正確」 的具體消息。顯示錯誤消息時，除了說哪裏錯了，還應提示用戶如何解決問題。不要用像「更新數據庫失敗」這樣的，要提示用戶怎麼作：「更新數據庫失敗，請確保登錄id和密碼正確」

16）錯誤處理和異常事件

不要「捕捉了異常卻什麼也不作」。若是隱藏了一個異常，你將永遠不知道異常到底發生了沒有。

發生異常時，給出友好的消息給用戶，但要精確記錄錯誤的全部可能細節，包括髮生的時間，和相關方法，類名等。

別寫太大的 try-catch 模塊。若是須要，爲每一個執行的任務編寫單獨的 try-catch 模塊。 這將幫你找出哪一段代碼產生異常，並給用戶發出特定的錯誤消息

若是應用程序須要，能夠編寫本身的異常類。自定義異常不該從基類SystemException派生，而要繼承於. IApplicationException。