Should a method comment include both a summary and return description when they're often so similar?

Question

I'm a proponent of properly documented code, and I'm well aware of the possible downsides of it. That is outside of the scope of this question.

I like to follow the rule of adding XML comments for every public member, considering how much I like IntelliSense in Visual Studio.

There is one form of redundancy however, which even an excessive commenter like me is bothered by. As an example take List.Exists().

/// <summary>
///     Determines whether the List<T> contains elements
///     that match the conditions defined by the specified predicate.
/// </summary>
/// <returns>
///     true if the List<T> contains one or more elements that match the
///     conditions defined by the specified predicate; otherwise, false.
/// </returns>
public bool Exists( Predicate<T> match )
{
    ...
}

Summary and returns are basically saying the same thing. I often end up writing the summary more from a returns perspective, dropping the returns documentation altogether.

Returns true when the List contains elements that match the conditions defined by the specified predicate, false otherwise.

Additionally, the returns documentation doesn't show up in IntelliSense, so I rather write any immediately relevant information in summary.

1. Why would you ever need to document returns separately from summary?
2. Any information on why Microsoft adopted this standard?

Answer 1

You can infer one from another, but those two sections remain separate, because it helps to focus on the one which interests the person when reviewing/using the code.

Taking your example, I would rather write:

/// <summary>
/// Determines whether the List<T> contains elements that match the conditions
/// defined by the specified predicate.
/// </summary>
/// <returns>
/// A value indicating whether at least one element matched the predicate.
/// </returns>
public bool Exists(Predicate<T> match)
{
    ...
}

• If I'm reviewing this code and I want to know what the method does, I read the summary, and that's all what I care about.

• Now, let's imagine I'm using your method and the return value I receive is strange, given the input. Now, I don't really want to know what the method does, but I do want to know something more about the return value. Here, <returns/> section helps, and I don't need to read the summary.

Again, in this example, you can infer the summary from <returns/>, and infer the expected return value from the summary. But taking the same argument to the extreme, there is no need to document your method at all in this case: the name of the method, put inside List<T>, with Predicate<T> match as a sole argument is quite explicit itself.

Remember, the source code is written once but read plenty of times. If you can reduce excise for the further readers of your code, while spending ten seconds writing an additional sentence in the XML documentation, do it.

Answer 2

My usage:
<summary>describes what the method does (to get the <returns>).
<returns> describes the return value.

Links to MSDN: <summary>. <returns>

Answer 3

Why would you ever need to document returns separately from summary?

I think if the summary part is really long and descriptive, it might be useful to have a separate, brief returns part at the end.

I usually write just the <summary> part in my own code, wording it the way you did saying "Returns _".

I put in any remarks that a caller should know that aren't obvious from the method name and parameters (and their names). Hopefully though, the method name and parameters make it obvious enough that the comment can be very brief.

Answer 4

I've been torn by the same philosophical question lately and I'm still not sure what a good solution is. But so far, this has been my approach...

• Method documentation only describes what external callers need to know. It doesn't talk about how this work is done internally, but mentions a) why the caller would want to call this method, b) what would be the expected results of calling the method. If there's a need to document how the method works, I put that into the code body itself.
• If a method has enough complexity to it, then general description and a separate [returns] section seems to be justified. You don't want the reader to read entire description and attempt to infer how to interpret the return value.
• If the method is so simple that the best way to describe what it does is to say something like "This method returns person's address", then I skip the [returns] section as adding would seem to go against the DRY principle and I'm a huge advocate of that. A lot of one-liner accessor methods seem to fall into this category.

Answer 5

The summary should be as descriptive as might be useful; the descriptions of parameters and return value should be short and sweet. If you have a choice between one word and five, use one. Let's tighten up your example:

true if the List contains one or more elements that match the conditions defined by the specified predicate; otherwise, false.

becomes

true if any element of List matches predicate; otherwise false.