Code Commenting: Do you put your code comments on Interfaces or on Concrete classes, or both?

Question

What is the best practice in documenting classes and interfaces. Say if you have a concrete class called Foo, that derives from an interface called IFoo. Where do you put your comments for your methods? Do you duplicate your comments on the Interface as well as the concrete class?

Here is an example where comments are duplicated:

public class Foo : IFoo
{
    /// <summary>
    /// This function does something
    /// </summary>        
    public void DoSomething()
    {
    }
}

public interface IFoo
{
    /// <summary>
    /// This function does something
    /// </summary>        
    void DoSomething();
}

Answer 1

I generally put them on both, however, they do not say the same thing. The interface's comment should describe the abstract purpose of this method/interface. While the concrete comment will talk about the implementation specifics of the method/class in the context of the interface's purpose.

Answer 2

I put them in both, but its a pain keeping them in sync, when in doubt I only put them on the interface.

I do this because I like the tooltip when using the code, which should almost always be using the interface...

Answer 3

I would put comments on both.

On interfaces I would comment on the intent behind the interface members and usage.

On implementations I would comment on the reasons for the specific implementation.

Answer 4

I don't really use them at all. Instead I make sure to structure the code and name all methods and variables in a way that its obvious what they do without comments. The problem with comments is that they don't compile and don't execute and are not tested by your unit tests, so its pretty much impossible to keep them in synch with the code.

Answer 5

Only for interfaces. Because in this case I don't need to synchronize them. My IDE helps me to see interface comments in concrete classes. And api document generator does the same.

Answer 6

Both, but I wish there was built in functionality to keep them in sync

Answer 7

Your example code doesn't use explicit interface implementation. The client of your code is going to need both since s/he can invoke the method either through a class object or interface reference. With explicit interface implementation you can omit the class method comment since the client can never see it. This is assuming you are using XML documentation to generate IntelliSense info.

Answer 8

A tag <referTo>System. .... </referTo> to link the comments would be ideal

Answer 9

Ideally, only the interface needs to be documented, since it defines the contract that every concrete implementation needs to fulfill.