How do you avoid redundancy in documentation comments? [closed]

Question

We just started using StyleCop and the one thing I'm having a hard time with is the documentation requirements. I don't want to debate the usefulness of the tool, I'm just wondering if anyone has any guidelines or ways of thinking about documenting methods that makes the comments actually useful. I find that my comments often contain a lot of repetition just to satisfy StyleCop's requirements, like:

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

Is there a standard way of phrasing a summary vs a returns description? What do you put in your param descriptions?

Answer 1

I try to avoid duplicates by describing the process as well in the summary. In parameters you can add details such as valid ranges, or how the user is expected to get this information. For the returns I also list any error conditions, for example:

/// <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

If it's being forced onto you, then you may just have to suffer with some repetition, seeing as you already use good self-documenting techniques like intelligent naming.

Other good things you could include in documentation would be: 1)Formatting - Are there any restrictions on userID, like "All users below 500 are admins" or something of that nature? These are good to comment with the param.

2) Exceptions - If your method is going to throw or pass one, document it so people using it will know to deal with it.

3) Code samples - showing how to use your method

4) Special Conditions - will the return object be in any kind of odd condition? If the userID isn't found, do you pass back a null or a blank/error PersonalInfoDTO?

And of course, on simple methods it'll seem like there's a lot of redundant information but more complex code can benefit immensely from thorough documentation.

Answer 3

Jayrdub:

Keep in mind that the point of those comments is to create documentation for your code. Redundancy is ok, since different portions of those comments may be used differently in different scenarios -- not all of your entire comment may be used in certain circumstances.

Although XML doc is useful for creating MSDN-style help files, it's also used extensively in intellisense and tooltips within Visual Studio. Your summary will be visible at certain times, your param tags will be visible at other times, and your returns tag will be visible at still other times. Sometimes they will all be visible together, and sometimes not.

In short, the redundancy is useful. It provides help to you as a programmer in different circumstances when you are using the method or class that it documents.