如何避免文档评论中的冗余？

我们刚开始使用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

如何避免文档评论中的冗余？

回答

相关问题