Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

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

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();
}
like image 344
7wp Avatar asked Dec 09 '09 17:12

7wp


2 Answers

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

like image 62
mfx Avatar answered Oct 08 '22 04:10

mfx


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.

like image 36
Oded Avatar answered Oct 08 '22 03:10

Oded