How do you avoid redundancy in documentation comments?

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

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

Useful and Redundant have nothing to do with each other.

You haven't defined "useful" in your question. Usually it means "more than required by stylecop". If you feel the need to write something more, then, write something more. Stylecop is the minimum; you are free to go above and beyond those minima.

In your case, since you're writing a summary of a function that does very little. It's very common that the formal elements (parameters and return types) and the summary will repeat each other. I'm not sure how this repetition fails the "useful" test. Perhaps if there's something missing you could add it. Feel free to expand and write more -- nothing stops you from writing "useful" documentation that is more than the minimum.

Redundant -- while tedious -- doesn't seem to fail to be useful.

Remember, your comments will wind up creating indexes as well as plain text pages. The formally structured parts are essential for indexing and formatting.

For more complex classes (and functions), the summary is a place to expand on nuance. For instance "why?" or "when it can and cannot be used", and "other constraints" and "code samples" and that kind of stuff that would be more useful.

At any time, you can --and should-- write more than the minimum. However, for trivial functions, there's no point in writing more than the minimum.

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

There is a reason for enforcing this standard, even if you feel that it is sometimes redundant information. (i.e. "userId -> the ID of the user") This comment also implicitly contains the information that there is NO additional constraints on that parameter.

So,

...
///<param name="angle"> 
///The angle in degrees. Must be below 360 and above 0.
///</param>
...

If you don't add that "Must be below x and above y" then you are stating that there is no restriction on the parameter.

Similarly for the < returns > tag. You may think that the return value is self explanatory, but the < returns > tag is where you should be telling the calling party whether or not this could return null on error. Or if it returns a single value, even if there is a list of possible responses.

This kind of information is very very important, and stylecop is just enforcing that you add it.

Answer 4

I tend to be very suspicious of tools that force you to add comments in very arbitrary places.

Don't get me wrong, I'm a strong advocate of comments. But comments like those in your example are pure "noise": they don't add anything useful, and any meaningful information, if any, is hidden behind the fluff.

If comments could be generated by an automatic tool... then humans have no business writing them in the first place. If that's mandatory for some other reason (generation of external documentation for instance), you should have some form of automated script to generate those, and place the results in an unobtrusive location.

Of course, there's lots of meaningful things you could say about this function's interface. What are the bounds on the parameters, for instance.

Answer 5

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 6

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.

Answer 7

There is a lot of repetition - the worst IMHO is Properties, where you are supposed to fill in the <value> describing the property, but intellisense only shows the <summary> which for a property can only really describe the same thing, so you end up saying the same thing twice.

I try to briefly summarise the property/method in the summary but put more detailed descriptions in the <param>, <value>, and <returns> fields so that they provide some genuinely more useful information. (e.g. whether they can be passed in as null, etc)

The second thing I do is use an add-in I've written to auto-generate and auto-update) the Doc comments, so that I minimise the work involved in documenting the code - if an automated tool can fill in most of the details for me, it minimises the effort involved in maintaining this "duplicated" information. It also auto-formats and word-wraps the comments to keep them tidy.

See http://www.atomineer.com/AtomineerUtils.html for more information and a free download.

Answer 8

You can make it useful:

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

For me, summary is the high-level "what is the purpose of this method" information, remarks is for further explanation, and see is where you can make it easy to move around your documentation. Each of those adds value.

I actually love documentation comments thanks to ReSharper. I've re-mapped the QuickDoc command to CTRL+SHIFT+Q.

Answer 9

If you're doing Java, you must be careful about complete documentation - the more you document, the less chances there are that users would find the things that are actually relevant. Adding extra markup only makes it worse.

You may want to consider only capturing "directives" or at least highlighting them very strongly.

See my detailed reply on "tips for writing a great javadoc" that are based on my Ph.D. research on this topic.

Answer 10

The problems are as follows ....

1. Right. No one is stopping you from writing comment but they become harder to maintain. Somebody reading the code can get confused if comment does not match the code. Admit we all change the code later and forget/dont get time to update them. ment
2. Some methods are really very simple and do not need any comment.
3. Its harder to read through a 1000 lines than 100 lines properly written code. Yes even with visual studio coloring
4. It takes lot of time to comment EVERY SINGLE METHOD in you code.
5. These Comments are ok if you are building a library but not for something not reusable..like a an small silverlight application.