C#代碼開發規範
文件狀態： [√] 草稿 [ ] 正式 [ ] 修改 | 文件標識： |
|
當前版本： | 1.1 | |
作 者： | Empty | |
聯繫電話： |
| |
最後更新： | 2017-04-07 |
日期 | 版本號 | 作者 | 說明 |
2017-4-2 | 1.0 | Empty | 創建 |
2017-4-7 | 1.1 | Empty | 添加前言、註釋規範與編碼規範 |
|
|
|
|
|
|
|
|
|
|
|
|
目 錄
爲了保證編寫出的程序都符合相同的規範，保證一致性、統一性而建立的程序編碼規範。
編碼規範對於程序員而言尤爲重要，有以下幾個原因：
1)一個軟件的生命週期中，80%的花費在於維護。
2)幾乎沒有任何一個軟件，在其整個生命週期中，均由最初的開發人員來維護。
3)編碼規範可以改善軟件的可讀性，可以讓程序員儘快而徹底地理解新的代碼。
每個軟件開發人員都必須遵守統一的編碼規範。
.2 適用範圍
本規範適用於《從零開始編寫自己的C# 框架》的開發。
.3 基本要求
儘量使代碼簡單直白。
2.
.1 字母大小寫約定
.1.1 說明
表達清晰的命名規範是程序規劃的核心，如果規範的命名能清晰的表達出相應的功能，就可以讓人“望文知意”，提高開發效率和系統的可維護性。反之，如果命名不能表達其含義，例如“aaa”、“bbb ()”，那麼將適得其反。
.1.2 Pascal風格
包含一到多個單詞，每一個單詞第一個字母大寫，其餘字母均小寫。例如：HelloWorld、SetName等。
.1.3 Camel風格
包含一到多個單詞，第一個單詞首字母小寫，其餘單詞首字母大寫。例如：name、productId等。
.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=newUsers();
Users model=newUsers();
Users userModel=newUsers();
const string const_String = "";（不同公司有不同的約定，具體根據自己公司情況設置而定）
Private stringGetProductName(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。