Code Commenting: Do you put your code comments on

Question

This question already has answers here:

Comment the interface, implementation or both? (8 answers)

Closed 6 months ago.

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

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

Answer 2

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 3

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

Answer 4

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

Answer 5

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 6

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.