原文：http://www.49028c.com/wulinfeng/archive/2012/08/31/2664720.html
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 規范目的
2 適用范圍
3 代碼注釋
3.1 代碼注釋約定
3.2 模塊頭部注釋規范
以一個物理文件為單元的都需要有模塊頭部注釋規范，例如：C#中的.cs文件
用于每個模塊開頭的說明，主要包括：（粗體字為必需部分，其余為可選部分）
示例如下：
3.3 方法注釋規范
1> C# 提供一種機制，使程序員可以使用含有xml 文本的特殊注釋語法為他們的代碼編寫文檔。在源代碼文件中，具有某種格式的注釋可用于指導某個工具根 據這些注釋和它們后面的源代碼元素生成XML。具體應用當中，類、接口、屬性、方法必須有<Summary>節，另外方法如果有參數及返回值，則必須有 <Param>及<Returns>節。示例如下：
/// <summary>
/// …
/// </summary>
/// <param name=””></param>
/// <returns></returns>
2> 事件不需要頭注解，但包含復雜處理時（如：循環/數據庫操作/復雜邏輯等），應分割成單一處理函數，事件再調用函數。
3> 所有的方法必須在其定義前增加方法注釋。
4> 方法注釋采用 /// 形式自動產生XML標簽格式的注釋。
標記
說明
備注
<c>
提供了一種將說明中的文本標記為代碼的方法
<code>
提供了一種將多行指示為代碼的方法
<example>
可以指定使用方法或其他庫成員的示例。一般情況下，這將涉及到 <code> 標記的使用。
<exception>
對可從當前編譯環境中獲取的異常的引用。
<include>
得以引用描述源代碼中類型和成員的另一文件中的注釋。
<list>
用于定義表或定義列表中的標題行。
<para>
用于諸如<summary>、<remarks> 或 <returns> 等標記內，使您得以將結構添加到文本中。
<param>
應當用于方法聲明的注釋中，以描述方法的一個參數。
<paramref>
提供了一種指示詞為參數的方法。
<permission>
得以將成員的訪問記入文檔。
<remarks>
用于添加有關某個類型的信息，從而補充由 <summary> 所指定的信息。
<returns>
應當用于方法聲明的注釋，以描述返回值。
<see>
得以從文本內指定鏈接。
<seealso>
對可以通過當前編譯環境進行調用的成員或字段的引用。
<summary>
應當用于描述類型或類型成員。
<value>
得以描述屬性。
示例圖如下：
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> 下表描述了不同類型標識符的大小寫規則：
標識符
大小寫
示例
命名空間
Pascal
namespace Com.Techstar.PRoductionCenter
類型
Pascal
public class DevsList
接口
Pascal
public interface ITableModel
方法
Pascal
public void UpdateData()
屬性
Pascal
Public int Length{…}
事件
Pascal
public event EventHandler Changed;
私有字段
Camel
private string fieldName;
非私有字段
Pascal
public string FieldName；
枚舉值
Pascal
FileMode{Append}
參數
Camel
public void UpdateData(string fieldName)
局部變量
Camel
string fieldName;
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 組件名稱縮寫列表
縮寫的基本原則是取組件類名各單詞的第一個字母，如果只有一個單詞，則去掉其中的元音，留下輔音。縮寫全部為小寫。
組件類型
縮寫
例子
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
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> 在一個類中，所有的屬性全部定義在一個屬性塊中：
Version：1.0.0
Date：2012.8.30
新聞熱點
疑難解答
