What informations to provide in Xml comments?

Question

When I write a method and I want to comment it, I write the same information into the summary tag.

Example:

/// <summary>
/// Get a <typeparamref name="Customer">customer</typeparamref> by its ID 
/// </summary>
/// <param name="id">customer id</param>
/// <returns>a <typeparamref name="Customer">customer</typeparamref></returns>
private Customer GetCustomerById(string id)
{
   ...
}

Finally, it this really useful? What info provide and in which tag to provide them?

Answer 1

Consider DRY (don't repeat yourself). The param entry describes the parameter, and the returns entry describes what is returned. The summary should give an overview of what the method does, not repeat the information from those other entries.

What your documentation is missing is actual documentation. A "string id" is a string that has an ID in it - that is self documenting. But how do I call this method: What comprises a valid user id? What will happen if I pass in a null or empty string? etc.

Here's a hypothetical example that includes documentation of what things are for and how to use the method:

/// <summary> Gets information on a customer </summary>
///
/// <param name='id'> A customer identifier in the form of a GUID string.
/// e.g. "{D8C447DD-0E7F-4C8B-A3E5-2C6E160D297B}".
/// Braces around the GUID are optional.
/// This parameter must be a valid Guid. </param>
///
/// <returns> A Customer record describing the given customer, or
/// null if the Customer is not found</returns>

If you use a tool like my addin (Atomineer Pro Documentation) then replicating these sort of parameter details around a class is trivial, so it need not be time consuming to document your methods well.

Answer 2

An answer to another question will also answer on yours:

Is providing documentation really useful?

Provide anything you want, what you see required and useful. This information will appear to a code consumer in Visual Studio as IntelliSense tooltip, like you see for .NET classes and members.

Answer 3

Xml documentation is pretty useful if you are developing a library. A help file can automatically be generated against these xml comments. See this for detailed discussion on generating the help file. For information about Xml documentation tag, check MSDN.

Answer 4

Sometimes method or property names are self explanatory, but that's not always the case. Event with your example. You should provide information what will happen if provided ID doesn't exist. Will your method throw an exception (if so, then what exception would it be) or maybe just return null, or some kind of general Customer.Empty value? Sometimes you could even provide some code sample.

Either way it's always a good practice to provide code documentation in any case.

Answer 5

In a lot of cases I find it best to cut out the return element entirely. It seems like your example is a great example of this. Thankfully, VStudio doesn't mark this as a bad comment with a warning. The reason I do this is because in 80%+ of the cases, my documentation basically describes what the return type is all about already, or, the name of the function is so blatantly obvious that it's a useless waste of time and energy, in my estimate, to include this, and it often leads to a violation of DRY.

Your example is a perfect example of this.

Customer GetCustomerById(string id)

If this was an int id, this function might not even need a comment. With a string, that's less clear and may use some clarification. But in either case, it seems like a waste of effort to provide an XML comment on the return type. Keep in mind this is a subjective question, some people may like for completion's sake to always include the return type comment, that's fine. I'm glad it is not required though, starting with VStudio's warning system.