C# 編碼規範、命名規則

1  規範目的 ……………………………………………………… 3

2  適用範圍 ……………………………………………………… 3

3  代碼註釋 ……………………………………………………… 3

　　3.1    代碼註釋約定............................................ 3

　　3.2    模塊頭部註釋規範...................................... 3

　　3.3    方法註釋規範............................................. 4

　　3.4    代碼行註釋規範.......................................... 6

　　3.5    變量註釋規範............................................. 7

4  命名規則 ……………………………………………………… 8

　　4.1    命名的基本約定.......................................... 8

　　4.2    各類標示符類型的基本約定......................... 9

　　4.3    組件名稱縮寫列表....................................... 10

5  其它規範 ……………………………………………………… 11

　　5.1    編程風格.................................................. 11

　　5.2    資源釋放.................................................. 13

　　5.3    錯誤處理.................................................. 13

　　5.4    其它......................................................... 14

 

 

1     規範目的

1. 一個軟件的生命週期中，80%的花費在於維護；
2. 幾乎沒有任何一個軟件，在其整個生命週期中，均由最初的開發人員來維護；
3. 編碼規範能夠改善軟件的可讀性，可讓程序員儘快而完全地理解新的代碼。爲了執行規範，每一個軟件開發人員必須一致遵照編碼規範；
4. 使用統一編碼規範的主要緣由，是使應用程序的結構和編碼風格標準化，以便於閱讀和理解這段代碼；
5. 好的編碼約定可以使源代碼嚴謹、可讀性強且意義清楚，與其它語言約定相一致，而且儘量的直觀。

 

2     適用範圍

1. 本規範主要以C#爲開發語言的規範，爲鮑亮實驗室的原則性規範；
2. 因爲本規範是爲撰寫程序而設計，因此適用於一切有關程序撰寫的工做事項。對於具體的每一個項目，可能須要對之進行裁剪和補存。
3. 適用人員：軟件工程專業的學生；
4. 適用產品：以C#編寫的程序。

 

3     代碼註釋

3.1    代碼註釋約定

1. 全部的方法和函數都應該以描述這段代碼的功能的一段簡明註釋開始（方法是幹什麼）。這種描述不該該包括執行過程細節（它是怎麼作的），由於這經常是隨時間而變的，並且這種描述會致使沒必要要的註釋維護工做，甚至更糟—成爲錯誤的註釋。代碼自己和必要的嵌入註釋將描述實現方法。
2. 當參數的功能不明顯且當過程但願參數在一個特定的範圍內時，也應描述傳遞給過程的參數。被過程改變的函數返回值和全局變量，特別是經過引用參數的那些，也必須在每一個過程的起始處描述它們。

3.2     模塊頭部註釋規範

以一個物理文件爲單元的都須要有模塊頭部註釋規範，例如：C#中的.cs文件

用於每一個模塊開頭的說明，主要包括：（粗體字爲必需部分，其他爲可選部分）

1. 文件名稱(File Name)： 此文件的名稱
2. 功能描述(Description)：   此模塊的功能描述與大概流程說明
3. 數據表(Tables)：             所用到的數據表，視圖，存儲過程的說明，如關係比較複雜，則應說明哪些是可擦寫的，哪些表爲只讀的。
4. 做者(Author)：
5. 日期(Create Date)：
6. 參考文檔(Reference)(可選)：          該檔所對應的分析文檔，設計文檔。
7. 引用(Using) (可選)﹕           開發的系統中引用其它系統的Dll、對象時，要列出其對應的出處，是否與系統有關﹙不清楚的能夠不寫﹚，以方便製做安裝檔。
8. 修改記錄(Revision History)：若檔案的全部者改變，則須要有修改人員的名字、修改日期及修改理由。
9. 分割符：*************************** (先後都要)

示例以下：

　　

3.3     方法註釋規範

　　1>  C# 提供一種機制，使程序員可使用含有XML 文本的特殊註釋語法爲他們的代碼編寫文檔。在源代碼文件中，具備某種格式的註釋可用於指導某個工具根據這些註釋和它們後面的源代碼元素生成XML。具體應用當中，類、接口、屬性、方法必須有<Summary>節，另外方法若是有參數及返回值，則必須有<Param>及<Returns>節。示例以下：

　　　　/// <summary>
　　　　/// … 　　　　/// </summary>
　　　　/// <param name=」」></param>
　　　　/// <returns></returns>

　　2>  事件不須要頭註解，但包含複雜處理時（如：循環/數據庫操做/複雜邏輯等），應分割成單一處理函數，事件再調用函數。

　　3>  全部的方法必須在其定義前增長方法註釋。

　　4>  方法註釋採用 /// 形式自動產生XML標籤格式的註釋。

 

　　　　示例圖以下：

　　　

　　5>  在公用類庫中的公用方法須要在通常方法的註釋後添加做者、日期及修改記錄信息，統一採用XML標籤的格式加註，標籤以下：

 

<Author>做者</Author>
<CreateDate>創建日期</CreateDate>
<RevisionHistory>    --修改記錄
    <ModifyBy>修改做者</ModifyBy>
    <ModifyDate>修改日期</ModifyDate>
    <ModifyReason>修改理由</ModifyReason>

    <ModifyBy>修改做者</ModifyBy>
    <ModifyDate>修改日期</ModifyDate>
    <ModifyReason>修改理由</ModifyReason>

    <ModifyBy>修改做者</ModifyBy>
    <ModifyDate>修改日期</ModifyDate>
    <ModifyReason>修改理由</ModifyReason>
</RevisionHistory>
<LastModifyDate>最後修改日期</LastModifyDate>

　　6>  一個代碼文件若是是由一人編寫，則此代碼文件中的方法無需做者信息，非代碼文件做者在此文件中添加方法時必需要添加做者、日期等註釋。

　　7>  修改任何方法，必需要添加修改記錄的註釋。

3.4     代碼行註釋規範

　　1>  若是處理某一個功能須要不少行代碼實現，而且有不少邏輯結構塊，相似此種代碼應該在代碼開始前添加註釋，說明此塊代碼的處理思路及注意事項等

　　2>  註釋重新行增長，與代碼開始處左對齊　　

　　3>  雙斜線與註釋之間以空格分開，示例圖以下所示：

　　

3.5     變量註釋規範

　　1>  定義變量時需添加變量註釋，用以說明變量的用途。

　　2>  Class級變量應以採用 /// 形式自動產生XML標籤格式的註釋，示例圖以下所示：　　                                                                                                

　　3>  方法級的變量註釋能夠放在變量聲明語句的後面，與先後行變量聲明的註釋左對齊，註釋與代碼間以Tab隔開。

 

4    命名規則

4.1     命名的基本約定

　　1>  要使用能夠準確說明變量/字段/類的完整的英文描述符，如firstName。對一些做用顯而易見的變量能夠採用簡單的命名，如在循環裏的遞增（減）變量就能夠被命名爲 「i」。

　　2>  要儘可能採用項目所涉及領域的術語。

　　3>  要採用大小寫混合，提升名字的可讀性。爲區分一個標識符中的多個單詞，把標識符中的每一個單詞的首字母大寫。不採用下劃線做分隔字符的寫法。

　　　　有兩種適合的書寫方法，適應於不一樣類型的標識符：

　　　　　　PasalCasing：標識符的第一個單詞的字母大寫；

　　　　　　camelCasing：標識符的第一個單詞的字母小寫。

　　4>  下表描述了不一樣類型標識符的大小寫規則：

　　5>  避免使用縮寫，若是必定要使用，就謹慎使用。同時，應該保留一個標準縮寫的列表，而且在使用時保持一致。

　　6>  對常見縮略詞，兩個字母的縮寫要採用統一大小寫的方式（示例：ioStream，   getIOStream）；多字母縮寫採用首字母大寫，其餘字母小寫的方式（示例：getHtmlTag）；

　　7>  避免使用長名字（最好不超過 15 個字母）。

　　8>  避免使用類似或者僅在大小寫上有區別的名字。

4.2     各類標示符類型的命名約定

　　1>  程序集命名

　　實驗室名稱（Lab）+ 項目名稱 + 模塊名稱（可選），例如：

　　　　中心服務器程序集：Lab.SeverCenter；

　　　　中心服務器業務邏輯程序集：Lab.SeverCenter.Business；

　　2>  命名空間命名

　　採用和程序集命名相同的方式：實驗室名稱（Lab）+ 項目名稱 + 模塊名稱。 另外，通常狀況下建議命名空間和目錄結構相同。例如：

　　　　中心服務器：Lab.SeverCenter；

　　　　中心服務器下的用戶控件：Lab.SeverCenter.UserControl；

　　　　中心服務器業務邏輯：Lab.SeverCenter.Business；

　　　　中心服務器數據訪問：Lab.SeverCenter.Data；

　　3>  程序集和DLL

　　l  大多數狀況下，程序集包含所有或部分可重用庫，且它包含在單個動態連接庫(DLL) 中。

　　l  一個程序集可拆分到多個DLL 中，但這很是少見，在此準則中也沒有說明。

　　l  程序集和DLL 是庫的物理組織，而命名空間是邏輯組織，其構成應與程序集的組織無關。

　　l  命名空間能夠且常常跨越多個程序集。能夠考慮以下模式命名DLL：

      　　  <Company>.<Component>.dll

   　　     例：Lab.SeverCenter.dll

　　4> 類和接口命名

　　l  類的名字要用名詞；

　　l  避免使用單詞的縮寫，除非它的縮寫已經廣爲人知，如HTTP。

　　l  接口的名字要以字母I開頭。保證對接口的標準實現名字只相差一個「I」前綴，例如對IComponent接口的標準實現爲Component；

　　l  泛型類型參數的命名：命名要爲T或者以T開頭的描述性名字，例如：

　　　　public class List<T>

　　　　public class MyClass<Tsession>

　　l  對同一項目的不一樣命名空間中的類，命名避免重複。避免引用時的衝突和混淆；

　　5> 方法命名

　　l  第一個單詞通常是動詞；

　　l  若是方法返回一個成員變量的值，方法名通常爲Get+成員變量名，如若返回的值 是bool變量，通常以Is做爲前綴。另外，若是必要，考慮用屬性來替代方法；

　　l  若是方法修改一個成員變量的值，方法名通常爲：Set + 成員變量名。同上，考慮 用屬性來替代方法。

　　6> 變量命名

　　l  按照使用範圍來分，咱們代碼中的變量的基本上有如下幾種類型，類的公有變量；類的私有變量（受保護同公有）；方法的參數變量；方法內部使用的局部變量。這些變量的命名規則基本相同，見標識符大小寫對照表。區別以下：

　　　　a)   類的公有變量按一般的方式命名，無特殊要求；

　　　　b)   類的私有變量採用兩種方式都可：採用加「m」前綴，例如mWorkerName;

　　　　c)   方法的參數變量採用camalString，例如workerName；

　　l  方法內部的局部變量採用camalString，例如workerName。

　　l  不要用_或&做爲第一個字母；

　　l  儘可能要使用短並且具備意義的單詞；

　　l  單字符的變量名通常只用於生命期很是短暫的變量：i,j,k,m,n通常用於integer；c,d,e 通常用於characters；s用於string

　　l  若是變量是集合，則變量名要用複數。例如表格的行數，命名應爲：RowsCount；

　　l  命名組件要採用匈牙利命名法，全部前綴均應遵循同一個組件名稱縮寫列表

4.3  組件名稱縮寫列表

　　縮寫的基本原則是取組件類名各單詞的第一個字母，若是隻有一個單詞，則去掉其中的元音，留下輔音。縮寫所有爲小寫。

 

5    其它規範

5.1      編程風格

　　1>  變量聲明：

　　爲了保持更好的閱讀習慣，請不要把多個變量聲明寫在一行中，即一行只聲明一個變量。

　　--例如： 　　String strTest1, strTest2; 　　--應寫成： 　　String strTest1; 　　String strTest2;

　　2>   代碼縮進：

　　l  一致的代碼縮進風格，有利於代碼的結構層次的表達，使代碼更容易閱讀和傳閱；

　　l  代碼縮進使用Tab鍵實現，最好不要使用空格，爲保證在不一樣機器上使代碼縮進保持一致，特此規定C#的Tab鍵寬度爲4個字符，設定界面以下(工具–選項)：

　　

　　l  避免方法中有超過5個參數的狀況，通常以2,3個爲宜。若是超過了，則應使用struct來傳遞多個參數。

　　l  爲了更容易閱讀，代碼行請不要太長，最好的寬度是屏幕寬度（根據不一樣的顯示分辯率其可見寬度也不一樣）。請不要超過您正在使用的屏幕寬度。（每行代碼不要超過80個字符。）

　　l  程序中不該使用goto語句。

　　l  在switch語句中老是要default子句來顯示信息。

　　l  方法參數多於8個時採用結構體或類方式傳遞

　　l  操做符/運算符左右空一個半角空格

　　l  全部塊的{}號分別放置一行，並嵌套對齊，不要放在同一行上 

　　3>    空白：

　　l  空行將邏輯相關的代碼段分隔開，以提升可讀性。

　　l  下列狀況應該老是使用兩個空行：

　　　　a)  一個源文件的兩個片斷(section)之間。

　　　　b)  類聲明和接口聲明之間。

　　l  下列狀況應該老是使用一個空行：

　　　　a)  兩個方法之間。

　　　　b)  方法內的局部變量和方法的第一條語句之間。

　　　　c)  塊註釋（參見"5.1.1"）或單行註釋（參見"5.1.2"）以前。

　　　　d)  一個方法內的兩個邏輯段之間，用以提升可讀性。

　　l  下列狀況應該老是使用空格：

　　　　a)  空白應該位於參數列表中逗號的後面，如：

　　　　　　void UpdateData(int a, int b)

　　　　b)  全部的二元運算符，除了"."，應該使用空格將之與操做數分開。一元操做符和操做數之間不因該加空格，好比：負號("-")、自增("++")和自減("--")。例如：

　　　　　　　　a += c + d;

　　　　　　　　d++;

　　　　c)  for 語句中的表達式應該被空格分開，例如：

　　　　　　　　for (expr1; expr2; expr3)

　　　　d)  強制轉型後應該跟一個空格，例如：

　　　　　　　　char c;

　　　　　　　　int a = 1;

　　　　　　　　c = (char) a;

5.2     資源釋放

　　全部外部資源都必須顯式釋放。例如：數據庫鏈接對象、IO對象等。

　　

5.3     錯誤處理

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

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

　　3>  只捕捉特定的異常，而不是通常的異常。

　　正確作法：

　　

　　錯誤作法：

　　

5.4     其它

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

　　2>  使用C#的特有類型，而不是System命名空間中定義的別名類型。

　　3>  別在程序中使用固定數值，用常量代替。

　　4>  避免使用不少成員變量。聲明局部變量，並傳遞給方法。不要在方法間共享成員變量。若是在幾個方法間共享一個成員變量，那就很難知道是哪一個方法在何時修改了它的值。

　　5>  別把成員變量聲明爲 public 或 protected。都聲明爲 private 而使用 public/protected 的屬性

　　6>  不在代碼中使用具體的路徑和驅動器名。 使用相對路徑，並使路徑可編程。

　　7>  應用程序啓動時做些「自檢」並確保所需文件和附件在指定的位置。必要時檢查數據庫鏈接。出現任何問題給用戶一個友好的提示。

　　8>  若是須要的配置文件找不到，應用程序需能本身建立使用默認值的一份。

　　9>  若是在配置文件中發現錯誤值，應用程序要拋出錯誤，給出提示消息告訴用戶正確值。

　　10>  DataColumn取其列時要用字段名，不要用索引號。
　　　　例： 正確DataColumn[「Name」]
    　　　　  很差 DataColumn[0]

　　11>  在一個類中，字段定義所有統一放在class的頭部、全部方法或屬性的前面。

　　12>  在一個類中，全部的屬性所有定義在一個屬性塊中：