Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?
share|improve this question
add comment

5 Answers

up vote 2 down vote accepted

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.

share|improve this answer
1  
you are calling a method and you don't want to know what it does!? –  jk. Nov 9 '11 at 16:22
1  
@jk: He is implying he already did that beforehand. Only when it fails, he wants to 'focus' on the return value. +1 for the last paragraph, that's essentially how I feel as well. Even if the documentation states an obvious fact as in my example, it reassures the reader of his expectations. When comments are managed properly it says: "this method is thought out properly, and does nothing more than what is mentioned here", as in the msdn documentation. –  Steven Jeuris Nov 9 '11 at 22:34
add comment

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.

share|improve this answer
    
Actually, writing it like that just made me realize the advantage of Microsoft's standard way of starting with "Determines whether ...". I feel it is more readable since it first explains what it is doing, before telling what the result of it is. That's one step less of indirection. I do agree that the returns from Microsoft is way too long. If it should do anything, it is to simply reassure that true means it matches, and false that it doesn't. –  Steven Jeuris Nov 9 '11 at 22:46
add comment

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.
share|improve this answer
    
Yup, I can connect with the mentioned points, and more or less follow them. The problem is that is a pretty subjective convention, which might be the reason why Microsoft just opted for always adding returns instead. I also notice they always use the same formulation, e.g. "true if ... ;otherwise, false." for boolean return values. I wonder whether they have specified a convention for that as well. –  Steven Jeuris Nov 9 '11 at 22:41
add comment

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

Links to MSDN: <summary>. <returns>

share|improve this answer
    
Thanks for the link. But nowhere does the msdn documentation of summary state it describes 'what the method does'. I down voted until you take the time to update your answer to clarify the difference between what msdn states and what you formulate it to be. ;p –  Steven Jeuris Nov 9 '11 at 14:39
2  
Whether MSDN says anything about it or not, this is actually a good guideline. In your example, you don't have to repeat the entire summary, you can just say "returns true if the predicate was matched." If somebody needs to know what constitutes a match, they can read the rest of the documentation. –  Blrfl Nov 9 '11 at 15:14
    
@Blrfl: I'm not saying the guideline is wrong. I'm saying it is wrong to reference a source, implying something is written there when it is not. Hence the down vote. I would very much like to see this answer edited. –  Steven Jeuris Nov 9 '11 at 15:39
    
@StevenJeuris: The links to the MSDN documentation were merely supplementary information. MSDN does NOT say, "When you have a <summary> and a <returns> do this". As Blrfl said, this is just a guideline one may or may not want to use. –  jberger Nov 9 '11 at 15:45
1  
@StevenJeuris: Although, because of the way it was written, I could see how someone may infer that it came from MSDN. –  jberger Nov 9 '11 at 15:52
show 2 more comments

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.

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.