您如何避免文档注释中的冗余？

Question

我们刚开始使用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) {...}

是否有一种标准的方式来表达摘要与退货描述？你在你的参数描述中加入了什么？

Answer 1

我尝试通过在摘要中描述该过程来避免重复.在参数中,您可以添加详细信息,例如有效范围或用户希望如何获取此信息.对于返回,我还列出了任何错误条件,例如:

/// <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) {...}

Answer 2

如果它被强加给你,那么你可能只需要经历一些重复,因为你已经使用了良好的自我记录技术,如智能命名.

您可以在文档中包含的其他好处是:1)格式化 - 对userID有任何限制,例如"500以下的所有用户都是管理员"还是那种性质的东西？这些很适合用param来评论.

2)异常 - 如果你的方法要抛出或传递一个,请记录它,以便使用它的人知道如何处理它.

3)代码示例 - 显示如何使用您的方法

4)特殊条件 - 返回对象是否处于任何奇怪的状态？如果找不到userID,您是否传回null或空白/错误的PersonalInfoDTO？

当然,在简单的方法上,似乎有很多冗余信息,但更复杂的代码可以从完整的文档中获益匪浅.

Answer 3

杰鲁杜布：

请记住，这些注释的目的是为您的代码创建文档。冗余是可以的，因为这些注释的不同部分在不同的场景中可能会有不同的使用方式——在某些情况下，并非所有的整个注释都会被使用。

尽管 XML 文档对于创建 MSDN 样式的帮助文件很有用，但它也广泛用于 Visual Studio 中的智能感知和工具提示。您的摘要将在某些时间可见，您的参数标签将在其他时间可见，您的退货标签将在其他时间可见。有时它们会一起可见，有时则不可见。

简而言之，冗余是有用的。当您作为程序员在不同情况下使用它所记录的方法或类时，它为您提供帮助。