C#注釋規範

5. 注釋

5.1. 注釋的基本約定

注釋應該增加代碼的清晰度；

保持注釋的簡潔，不是任何代碼都需要注釋的，過多的注釋反而會影響代碼的可讀性。

注釋不要包括其他的特殊字元。

建議先寫注釋，後寫代碼，注釋和代碼一起完成

如果語句塊（比如循環和條件分枝的代碼塊）代碼太長，嵌套太多，則在其結束“｝”要加上注釋，标志對應的開始語句。如果分支條件邏輯比較複雜，也要加上注釋。

在VS2005環境中通過配置工程編譯時輸出XML文檔檔案可以檢查注釋的完整情況，如果注釋不完整會報告編譯警告；

5.2. 注釋類型

5.2.1. 塊注釋

主要用來描述檔案，類，方法，算法等，放在所描述對象的前邊。具體格式以IDE編輯器輸入“///”自動生成的格式為準，另外再附加我們自定義的格式，如下所列：

/// <Remark>作者，建立日期，修改日期</Remark >

對類和接口的注釋必須加上上述标記，對方法可以視情況考慮

5.2.2. 行注釋

主要用在方法内部，對代碼，變量，流程等進行說明。整個注釋占據一行。

5.2.3. 尾随注釋

與行注釋功能相似，放在代碼的同行，但是要與代碼之間有足夠的空間，便于厘清。例：

int m = 4 ; // 注釋

如果一個程式塊内有多個尾随注釋，每個注釋的縮進要保持一緻。

5.3. 注釋哪些部分

項目	注釋哪些部分
參數	參數用來做什麼 任何限制或前提條件
字段/屬性	字段描述
類	類的目的 已知的問題 類的開發/維護曆史
接口	目的 它應如何被使用以及如何不被使用
局部變量	用處/目的
成員函數注釋	成員函數做什麼以及它為什麼做這個 哪些參數必須傳遞給一個成員函數 成員函數傳回什麼 已知的問題 任何由某個成員函數抛出的異常 成員函數是如何改變對象的 包含任何修改代碼的曆史 如何在适當情況下調用成員函數的例子适用的前提條件和後置條件
成員函數内部注釋	控制結構 代碼做了些什麼以及為什麼這樣做 局部變量 難或複雜的代碼 處理順序

5.4. 程式修改注釋

新增代碼行的前後要有注釋行說明，對具體格式不作要求，但必須包含作者，新增時間，新增目的。在新增代碼的最後必須加上結束标志；

删除代碼行的前後要用注釋行說明，删除代碼用注釋原有代碼的方法。注釋方法和内容同新增；删除的代碼行建議用#region XXX #endregion 代碼段折疊，保持代碼檔案幹淨整潔

修改代碼行建議以删除代碼行後再新增代碼行的方式進行（針對别人的代碼進行修改時，必須标明，對于自己的代碼進行修改時，酌情進行）。注釋方法和内容同新增；