如何避免文檔評論中的冗餘？

我們剛開始使用StyleCop，而且我很難與文檔要求一一對應。我不想辯論這個工具的實用性，我只是想知道是否有人有任何指導方針或思考方法來記錄使這些評論真正有用的方法。我發現，我的意見往往含有大量的重複恰好滿足了StyleCop的要求，如：如何避免文檔評論中的冗餘？

/// <summary> 
    /// Gets a dto of personal info. 
    /// </summary> 
    /// <param name="userId"> 
    /// The id of the user. 
    /// </param> 
    /// <returns> 
    /// A dto containing personal info. 
    /// </returns> 
    public PersonalInfoDTO GetPersonalInfoDTO(int userId) {...}

有沒有措辭摘要Vs的回報描述的標準方法？你把什麼放在你的參數描述中？

來源

2009-04-22 JeremyWeir

我只想借此機會說我很高興Javadoc不是基於XML的。 – 2009-04-22 18:51:06

@ mmyers：這與這個問題有關怎麼樣？你最終在Javadoc或XML中遇到同樣的問題。 – Randolpho 2009-04-22 18:54:12

@Randolpho：這不相關。我只是在觀察，這個文檔評論將更容易閱讀Javadoc形式。畢竟，文檔評論不僅僅是用於解析的工具。 – 2009-04-22 19:05:23

我試圖通過在摘要中描述過程來避免重複。在參數中，您可以添加有效範圍等詳細信息，或者希望用戶獲得此信息的方式。爲了回報我還列出任何錯誤條件，例如：

/// <summary> 
/// Gets a dto of personal info by querying the current list of users (or active directory or SQL) 
/// </summary> 
/// <param name="userId"> 
/// The id of the user. Must be greater than 0. The ID is stored in the application context or can be retrieved by a call to GetUserIdByName. 
/// </param> 
/// <returns> 
/// A dto containing personal info. Returns null if the specified user information was not found. 
/// </returns> 
public PersonalInfoDTO GetPersonalInfoDTO(int userId) {...}

來源

2009-04-22 18:57:20 esac

「記錄，使評價真正有用的方法。我覺得我的意見往往含有大量的重複恰好滿足了StyleCop的要求」

有用的和冗餘無關彼此。

你還沒有在你的問題中定義「有用」。通常它的意思是「超過stylecop要求」。如果你覺得有必要寫更多東西，那麼寫更多的東西。 Stylecop是最低的;你可以自由地超越最低限度。

就你而言，因爲你正在編寫一個功能非常小的摘要。形式元素（參數和返回類型）和摘要會重複出現是很常見的。我不確定這種重複如何不能通過「有用的」測試。也許如果有什麼失蹤你可以添加它。隨意擴展和書寫更多 - 沒有什麼能阻止你編寫超過最低限度的「有用的」文檔。

冗餘 - 雖然乏味 - 似乎沒有失效。

請記住，您的評論將結束創建索引以及純文本頁面。正式結構化的部分對索引和格式化非常重要。

對於更復雜的類（和函數），摘要是擴展細微差別的地方。例如「爲什麼？」或「什麼時候可以或不可以使用」，「其他限制」和「代碼示例」以及那種更有用的東西。

在任何時候，您都可以 - 並且應該 - 寫入更多的最小值。但是，對於微不足道的功能，寫入超過最低限度是沒有意義的。

來源

2009-04-22 18:51:52

如果它被強迫到你身上，那麼你可能不得不承受一些重複，因爲你已經使用了好的自我記錄技術，比如智能命名。

其他的好東西，你可能包括的文件將是： 1）格式 - 有沒有對用戶ID的任何限制，如「低於500所有用戶都是管理員」或類似這種事情？這些參數很好評論。 2）例外 - 如果你的方法要拋出或傳遞一個，記錄它，以便使用它的人知道處理它。

3）代碼示例 - 說明如何使用你的方法

4）特殊條件 - 將返回的對象是任何形式的奇條件？如果找不到用戶標識，您是否返回null或空白/錯誤PersonalInfoDTO？

當然，就簡單的方法而言，它似乎有很多冗餘信息，但更復雜的代碼可以從徹底的文檔中受益匪淺。

來源

2009-04-22 18:55:12 CodexArcanum

即使您覺得它有時是冗餘信息，也有強制執行此標準的原因。（即「userId - >用戶的ID」）該評論還隱含地包含對該參數沒有額外約束的信息。

所以，

... 
///<param name="angle"> 
///The angle in degrees. Must be below 360 and above 0. 
///</param> 
...

如果不添加「必須低於X和Y上面」，那麼就表示沒有對參數沒有限制。

同樣爲<返回>標記。你可能認爲返回值是自我解釋的，但是<返回>標記是你應該告訴主叫方這個錯誤是否可以返回null的地方。或者，如果它返回單個值，即使有可能的響應列表。

這種信息非常重要，stylecop只是強制你添加它。

來源

2009-04-22 18:55:19 DevinB

我傾向於非常懷疑那些強制您在任意位置添加註釋的工具。

不要誤會我的意思，我是一個強烈的評論倡導者。但是在你的例子中的評論是純粹的「噪音」：它們沒有添加任何有用的東西，任何有意義的信息（如果有的話）都隱藏在絨毛後面。

如果評論可以通過自動工具生成......那麼人類就沒有業務將它們寫在第一位。如果由於其他原因（例如生成外部文檔）而強制執行此操作，則應該使用某種形式的自動腳本來生成這些腳本，並將結果放置在不顯眼的位置。

當然，有很多有意義的事情可以說這個函數的接口。例如，參數的界限是什麼。

來源

2009-04-22 18:56:57 Kena

Jayrdub：

請記住，這些意見的點是爲你的代碼中創建的文檔。冗餘是好的，因爲這些評論的不同部分可能在不同的情況下使用不同 - 在某些情況下，並不是所有的評論都可以使用。

雖然XML文檔是一個用於創建MSDN形式的幫助文件是有用的，它也廣泛地在Visual Studio中的IntelliSense和工具提示使用。你的總結會在特定的時間不到，您的param標籤會在其他時間可見，你的回報標籤會顯示在另一些時間。有時他們會一起看到，有時候不會。

總之，冗餘是有用。它提供了幫助您在不同的情況下，一個程序員，當你正在使用的方法或類，它的文檔。

來源

2009-04-22 18:59:12 Randolpho

有很多重複 - 最差的恕我直言是屬性，在那裏你應該填寫<值>描述財產，但intellisense只顯示<摘要>哪些屬性只能真正描述相同事情，所以你最終會說同樣的事情兩次。

我儘量簡明扼要地總結總結屬性/方法，但放在< PARAM更詳細的說明>，< value>和<回報>字段，以便他們提供一些真正更多有用的信息。（例如：是否他們可以爲空，等傳遞）

我做的第二件事是使用一個外接我已經寫了自動生成和自動更新）的文檔註釋，所以我儘量少參與記錄代碼的工作 - 如果一個自動化工具可以爲我填充大部分細節，它將維護這些「重複」信息所需的工作量降到最低。它還自動格式化和評論文字，以保持整潔。

查看http://www.atomineer.com/AtomineerUtils.html瞭解更多信息和免費下載。

來源

2009-04-28 21:51:25

你可以把它有用：

/// <summary> 
/// Gets the user's personal information. 
/// </summary> 
/// <remarks> 
/// We need this data transfer object in order to bridge Backend.SubsystemA 
/// and Backend.SubsystemB. The standard <see cref="PersonalInfo"/> won't 
/// work. 
/// </remarks> 
/// <param name="userId">Integer representing the user's ID.</param> 
/// <returns> 
/// <see cref="PersonalInfoDTO"/> representing the user, or <c>null</c> 
/// if not available. 
/// </returns> 
public PersonalInfoDTO GetPersonalInfoDTO(int userId) {...}

對於我來說，summary是高層次的「什麼是這種方法的目的」的信息，remarks是進一步解釋，see在這裏你可以做移動文檔很容易。這些都增加了價值。

我真的很喜歡文檔評論感謝ReSharper。我已將QuickDoc命令重新映射到CTRL+SHIFT+Q。

來源

2009-04-28 22:09:21 bbrown

如果你在做Java，你必須小心完整的文檔 - 文檔越多，用戶就會發現實際相關的東西的機會越少。增加額外的標記只會使情況變得更糟。

您可能想要考慮只捕獲「指令」或至少強調它們的突出顯示。

看到我的詳細回覆"tips for writing a great javadoc"這是基於我的博士學位。研究這個話題。

來源

2009-04-28 22:10:08 Uri

是如下問題....

權。沒有人阻止你寫評論，但他們變得更難以維持。如果評論與代碼不匹配，讀代碼的人可能會感到困惑。承認我們以後都會更改代碼，並忘記/沒有時間來更新它們。片
一些方法非常簡單，不需要任何評論。
它難以通過1000行讀取比100行正確書寫的代碼。即使在視覺工作室着色的情況下也是如此
需要很多時間在您的代碼中評論每種單一方法。
這些評論是好的，如果你正在建立一個圖書館，但不適用於不可重複使用的東西..就像一個小的Silverlight應用程序。

來源

2009-09-24 17:57:24 Tanmoy

如何避免文檔評論中的冗餘？

回答

相關問題