Should you write XML comments for Interfaces, concrete implementations, or both?

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?

possible duplicate of [Comment the interface, implementation or both?](http://stackoverflow.com/questions/759703/comment-the-interface-implementation-or-both) — Yuriy Faktorovich, Apr 05 '11 at 21:10

score 10 · Accepted Answer · answered Apr 05 '11 at 21:32

10

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.

answered Apr 05 '11 at 21:32

Tomas Petricek

240,744
19
378
553

(I didn't see this in the "possible duplicate" answer, so I'm posting it here, because it is C# specific answer) – Tomas Petricek Apr 05 '11 at 21:35
I was unaware of the `` tag. Thank you. If it's okay to comment both then I think I prefer to include more verbose comments on the implementing class and generic ones on the interface (as per my example in the question). I don't really see it as repeating myself and as you said, it's readable in the source. However, I like this a lot and will probably find it useful in other projects. – CatDadCode Apr 05 '11 at 21:38
3

+1, but as someone that doesn't like comments, this seems like an even worse idea. My biggest beef with comments is they can obscure functionality especially by getting out of date. This creates an extra level of abstraction making it harder to keep them up to date. – Yuriy Faktorovich Apr 07 '11 at 18:38
In the three years since I originally asked this question, I've come to understand what @YuriyFaktorovich was talking about. Comments are only additive value if you keep them up to date as the code changes. I've come back to legacy code and noticed that more than a few comments get out of date as the code changes. You get jaded to their presence and kind of forget about them. – CatDadCode May 13 '14 at 15:30
Sorry but that makes no sense.. Comments are not meant to be verbose. If you are writing a comment and it gets 'out of date' either your comment was way too detailed, or your method was poorly named/implemented to begin with. It shouldn't be possible for a method comment to get out of date, because that method should 1) have an interface, and 2) be doing the same thing it's always been doing. If it's really doing something different, write a new method. – Robert Noack Mar 01 '15 at 18:33
Comments do get out of date as code changes, even if you follow all the guidelines you laid out. Good comments outline the accepted parameters and return value of a method. When someone adds/changes/removes an argument on a method and doesn't update the comment, that is a perfectly valid change to a method that does not merit a new method and now the comment is out of date because of laziness. I wasn't even arguing against comments, I'm just saying I understood Yuriy's point. Just because a method performs the same operation it always has does not mean the interface never gets updated... – CatDadCode Jul 24 '15 at 19:12

score 3 · Answer 2 · answered Apr 05 '11 at 21:40

Prefer to comment both. Remember that the interface method definition should contain all of the information the consumer requires to either implement or call it. The implementation is relevant to consumers as well as far as choosing which one to use, so it should be appropriate to comment as well.

The bottom line is to err on the side of more clarity rather than less.

score 0 · Answer 3 · answered Jan 18 '18 at 17:01

Document you interfaces.

If you implementation is more general or more specific e.g. can work with wider inputs or returns or throws more specific outputs, then document that on the implementation.

If the implementation does not differ from the interface, then you can use <inheritdoc />.

Related: Inherit documentation in C#?

Should you write XML comments for Interfaces, concrete implementations, or both?

3 Answers3