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