Question

I am interested in where I should apply my XML comments. Should I put a more generic XML comment in the interface and a more descriptive one on the implementing class? Like this:

public interface IObjectRepository
{
    /// <summary>
    ///    Returns an object from the respository that contains the specified ID.
    /// </summary>
    Object GetObject(int Id);
}

public ObjectRepository : IObjectRepository
{
    /// <summary>
    ///    Retrieves an object from the database that contains the specified ID.
    /// </summary>
    public Object GetObject(int Id)
    {
        Object myData = // Get from DB code.
        return myData;
    }
}

I did not include <param> for simplicity’s sake.

Is that a good practice for comments or is there a different way? Do I just skip commenting the interface?

Answer 1

You can define the comment in a separate file and then use the <include> tag (see MSDN). This way, you can write the comment just once, but include it as a documentation in multiple different places (e.g. the declaration and the implementation of an interface).

Of course, this requires a bit more discipline, because it is more difficult to write. It is also a bit less useful, because you won’t see them in the source code. However, if you want to use XML comments to build documentation, then it is probably a good approach.