我们刚刚开始使用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) {...}
是否有一种标准的方法来表达摘要与退货说明？你在你的参数描述中加入了什么？
答案 0 :(得分：9)
我尝试通过在摘要中描述该过程来避免重复。在参数中，您可以添加详细信息，例如有效范围或用户希望如何获取此信息。对于返回，我还列出了任何错误条件，例如：
/// <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) {...}
答案 1 :(得分：7)
如果它被强加给你，那么你可能不得不忍受一些重复，因为你已经使用了良好的自我记录技术，如智能命名。
您可以在文档中包含的其他好处是： 1）格式化 - 对userID有任何限制，例如“500以下的所有用户都是管理员”还是那种性质的东西？这些很适合用param评论。
2）异常 - 如果你的方法要抛出或传递一个，请记录下来，以便使用它的人知道如何处理它。
3）代码示例 - 显示如何使用您的方法
4）特殊条件 - 返回对象是否处于任何奇怪的状态？如果找不到userID，您是否传回null或空白/错误的PersonalInfoDTO？
当然，在简单的方法上，似乎有很多冗余信息，但更复杂的代码可以从完整的文档中获益匪浅。
答案 2 :(得分：4)
即使您认为有时候是冗余信息，也有理由执行此标准。 （即“userId - ＆gt;用户的ID”）此注释还隐含地包含对该参数没有其他约束的信息。
所以，
...
///<param name="angle">
///The angle in degrees. Must be below 360 and above 0.
///</param>
...
如果你没有添加“必须低于x且高于y”，那么你就说明参数没有限制。
同样适用于＆lt;返回＆gt;标签。您可能认为返回值是自我解释的，但＆lt;返回＆gt; tag是你应该告诉主叫方是否可以在出错时返回null的地方。或者，如果它返回单个值，即使存在可能的响应列表。
这种信息非常重要，而stylecop只是强制你添加它。
答案 3 :(得分：4)
Jayrdub：
请注意，这些评论的点是为您的代码创建文档。冗余是可以的，因为这些评论的不同部分可能在不同场景中使用不同 - 并非所有评论都可以在某些情况下使用。
尽管XML doc对于创建MSDN样式的帮助文件很有用，但它也广泛用于Visual Studio中的intellisense和工具提示。您的摘要会在特定时间显示，您的参数标记将在其他时间显示，并且您的返回标记将在其他时间显示。有时他们会一起看到，有时也看不到。
简而言之，冗余 非常有用。当您使用它所记录的方法或类时，它在不同情况下为您作为程序员提供帮助。
答案 4 :(得分：1)
“记录使评论真正有用的方法。我发现我的评论通常包含很多重复，只是为了满足StyleCop的要求”
有用和冗余彼此无关。
您的问题中没有定义“有用”。通常它意味着“超过stylecop所要求的”。如果你觉得需要写更多东西，那就写点更多。 Stylecop是最低的;你可以自由地超越那些最低点。
在你的情况下，因为你正在编写一个功能很少的函数摘要。形式元素（参数和返回类型）和摘要将相互重复是很常见的。我不确定这种重复是如何失败的“有用”测试。也许如果缺少，您可以添加它。随意扩展和写更多 - 没有什么能阻止你编写超过最低限度的“有用”文档。
冗余 - 虽然单调乏味 - 但似乎没有用处。
请记住，您的评论最终会创建索引以及纯文本页面。正式结构化的部分对于索引和格式化至关重要。
对于更复杂的类（和函数），摘要是一个扩展细微差别的地方。例如“为什么？”或“何时能够和不能使用”，以及“其他约束”和“代码样本”以及那些更有用的东西。
在任何时候，您都可以 - 并且应该 - 写出更多而不是最低限度。但是，对于琐碎的函数，写入的内容超过最小值是没有意义的。
答案 5 :(得分：0)
我倾向于非常怀疑那些迫使你在非常随意的地方添加评论的工具。
不要误会我的意思，我是评论的坚定拥护者。但是像你的例子中的那些评论是纯粹的“噪音”：它们没有添加任何有用的东西，任何有意义的信息，如果有的话，都隐藏在绒毛背后。
如果评论可以通过自动工具生成......那么人类首先就没有商业写作。如果出于某些其他原因（例如生成外部文档）这是强制性的，那么您应该使用某种形式的自动脚本来生成这些内容，并将结果放在一个不显眼的位置。
当然，关于这个功能的界面，你可以说很多有意义的事情。例如，参数的界限是什么。
答案 6 :(得分：0)
有很多重复 - 最糟糕的恕我直言是属性，你应该填写＆lt; value＆gt;描述属性，但intellisense只显示＆lt; summary＆gt;对于一个属性来说，它只能真正描述同一个东西，所以你最终会说两次相同的东西。
我尝试简要总结摘要中的属性/方法，但在＆lt; param＆gt;，＆lt; value＆gt;和＆lt; returns＆gt;中添加了更详细的描述。字段，以便它们提供一些真正更有用的信息。 （例如，它们是否可以作为null传递等）
我要做的第二件事是使用我写的自动生成和自动更新的插件来评论文档注释，以便最大限度地减少记录代码所涉及的工作 - 如果自动化工具可以填写对我来说，大多数细节都可以最大限度地减少维护这些“重复”信息的工作量。它还会自动格式化并自动换行注释以使其保持整洁。
有关详细信息和免费下载，请参阅http://www.atomineer.com/AtomineerUtils.html。
答案 7 :(得分：0)
你可以使它变得有用：
/// <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。
答案 8 :(得分：0)
如果您正在使用Java，则必须注意完整的文档 - 您记录的内容越多，用户找到实际相关内容的可能性就越小。添加额外的标记只会让它变得更糟。
您可能希望仅考虑捕获“指令”或至少强烈强调它们。
请参阅基于我的博士学位的"tips for writing a great javadoc"的详细回复。关于这个主题的研究。
答案 9 :(得分：0)
问题如下......