使用XML注釋記錄C＃代碼的最佳實踐是什么？

Question

我正在編寫一些我剛編寫的新代碼，並將NDoc sytle注釋添加到我的類和方法中。 我希望生成一個非常好的MSDN樣式文檔供參考。

一般來說，在為類和方法編寫注釋時，有哪些好的指導原則？ NDoc評論應該說什么？ 他們應該怎么說？

我發現自己正在研究.NET框架評論所說的內容，但這種情況會變得很快; 如果我能有一些好的規則來指導自己，我可以更快地完成我的文檔。

Answer 1

在用於構建API文檔的注釋中，您應該：

• 解釋方法或屬性的作用，為什么它存在，並解釋任何對代碼的普通消費者不言自明的域概念。

• 列出參數的所有前提條件（不能為空，必須在一定范圍內等）

• 列出可能影響調用者處理返回值的任何后置條件。

• 列出方法可能拋出的任何異常（以及在什么情況下）。

• 如果存在類似的方法，請解釋它們之間的差異。

• 注意任何意外的事情（例如修改全局狀態）。

• 列舉任何副作用，如果有的話。

Answer 2

如果您最終得到的評論不會增加任何價值，那么它們就是浪費。

例如

/// <summary>
/// Gets manager approval for an action
/// </summary>
/// <param name="action">An action object to get approval for</param>
public void GetManagerApprovalFor(Action action)

...你絕對沒有添加任何價值，只是添加了更多代碼來維護。

很多代碼都充斥着這些多余的評論。

Answer 3

StyleCop提供代碼和注釋樣式的提示。 它提供的建議符合MSDN文檔樣式。

至於評論的內容，它應該為您的代碼的用戶提供足夠的信息，說明期望的行為類型。 它還應該回答用戶可能遇到的潛在問題。 因此，嘗試將您的代碼用作對代碼一無所知的人，或者甚至更好，請其他人這樣做。

Answer 4

對於屬性，您的注釋應指示屬性是只讀，只寫還是讀寫。 如果你查看所有正式的MS文檔，屬性文檔注釋總是以“獲取...”，“獲取或設置...”開頭，並且（很少，通常避免只寫屬性）“設置......”

Answer 5

不要忘記什么是有效的XML。 例如：

/// <Summary>
/// Triggers an event if number of users > 1000
/// </Summary>

（錯誤：XML無效）。

Answer 6

我編寫<summary>注釋以包含我想知道的信息，如果我是調用該函數的那個​​（或實例化該類）。

我編寫<remarks>注釋以包含我想要知道的信息，如果我負責調試或增強該函數或類。 注意：這並不能取代良好的內聯注釋。 但有時候對函數/類的內部工作原理的一般概述非常有用。

Answer 7

正如MSDN頁面上所述，您使用XML文檔注釋自動生成文檔，因此制造商會感覺您是否正在編寫API並且不希望在代碼和文檔中都使用兩次，並且還可以將它們保存在同步 - 每次更改代碼時，都會修改相應的注釋並重新生成文檔。

使用/doc進行編譯，編譯器將在源代碼中搜索所有XML標記並創建XML文檔文件，然后使用Sandcastle等工具生成完整的文檔。

Answer 8

關於評論的一點是更新它們。 太多人改變了一個功能，然后不改變評論以反映變化。