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

Question

关闭。这个问题是opinion-based .它目前不接受答案。












想改善这个问题吗？更新问题，以便可以通过 editing this post 用事实和引文回答问题.

3年前关闭。




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