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();
}

回答1:

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.

回答2:

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.

回答3:

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...

回答4:

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.

回答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.

回答6:

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

回答7:

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

回答8:

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.

回答9:

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

来源：https://stackoverflow.com/questions/1875440/code-commenting-do-you-put-your-code-comments-on-interfaces-or-on-concrete-clas

标签

comments

xml-comments