C#程式碼開發規範

本記錄

目    錄

1. 

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

編碼規範對於程式設計師而言尤為重要，有以下幾個原因：

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

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

3)編碼規範可以改善軟體的可讀性，可以讓程式設計師儘快而徹底地理解新的程式碼。

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

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

儘量使程式碼簡單直白。

2.   

表達清晰的命名規範是程式規劃的核心，如果規範的命名能清晰的表達出相應的功能，就可以讓人“望文知意”，提高開發效率和系統的可維護性。反之，如果命名不能表達其含義，例如“aaa”、“bbb ()”，那麼將適得其反。

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

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

1)     除了引數與變數外，所有名稱空間名稱、類、函式、介面、屬性等名稱的命名，使用 Pascal 風格。

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

約定的是如何選擇最適當的名稱，這些準則適用於所有識別符號命名。

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=newUsers();

Users model=newUsers();

Users userModel=newUsers();

const string const_String = "";（不同公司有不同的約定，具體根據自己公司情況設定而定）

      Private stringGetProductName(int id)

{

           return"";

}

5)    不要使用成員屬性作為成員變數的字首（其他變數命名也一樣）

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

1)    通常，不應使用縮寫

2)    除非這種縮寫已廣泛接受，又或者團隊當中大家都認可一種縮寫

例如，使用 OnButtonClick，如果團隊中普遍認可OnBtnClick這種寫法也是可以的。

名稱空間命名採用Pascal風格，取名的一般規則如下。

CompanyName. ProjectName （公司名稱.專案名稱）

例如：

Microsoft.Office

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

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

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

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

1)    按照 Pascal 大小寫格式，使用名詞或名詞短語為類、介面和值型別命名

2)    介面命名以字母 I 為字首

例如：IComponent

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

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

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

資料夾以功能模組名稱，按照 Pascal 大小寫格式命名。

比如後端管理功能以及許可權相關功能，全部放到Systems資料夾裡。

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

///<summary>

///模組編號：<模組編號，可以引用系統設計中的模組編號>

///作用：<對此類的描述，可以引用系統設計中的描述>

///作者：作者中文名

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

///</summary>

如果模組有修改，則每次修改必須新增以下注釋：

///<summary>

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

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

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

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

///</summary>

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

///<summary>

///屬性說明

///</summary>

在類的方法宣告前必須以以下格式編寫註釋

///<summary>

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

///</summary>

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

///<returns>

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

///</returns>

程式碼間註釋分為單行註釋和多行註釋：

單行註釋：

//<單行註釋>

多行註釋：

/*多行註釋1

多行註釋2

多行註釋3*/

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

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

      *   程式碼塊功能名稱

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

//<單行註釋>

         或

/*多行註釋1

多行註釋2*/

或者也可以使用下面方法：

/********* 程式碼塊功能名稱開始************/

//<單行註釋>

//<單行註釋>

/********* 程式碼塊功能名稱結束************/

註釋說明

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

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

C.     如果因為某種原因使用了複雜艱澀的原理，為程式配備良好的文件和更多的註釋。

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。