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.