Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

I'm working on an application that uses Inversion of Control to achieve loose coupling between the Data Access and Business Layers.

Having an ILoanApplicationRepository and a LoanApplicationRepository, where should I store the XML Comments that document the class members? on the interface or on the concrete class? should I do it on both?

share|improve this question

3 Answers 3

up vote 10 down vote accepted

Ideally, both. In the interface, you can describe the expected behavior of the interface, and in the class you can describe the behavior of the implementation.

Of course, this is a huge amount of overkill and duplication in many cases, in which case I would suggest documenting in the interface only, primarily because in most cases this is what would be exposed in Intellisense.

Documenting the classes is really only a concern if you will be interacting with both the interface and the classes when developing.

public interface ILoanApplicationRepository
{
    /// <summary>
    /// Gets the next available application ID.
    /// </summary>
    public int GetNextApplicationId();
}

public class HttpLoanApplicationRepository : ILoanApplicationRepository
{
    /// <summary>
    /// Gets the next available application via /REST/Ids/Next
    /// </summary>
    public int GetNextApplicationId()
    {
        var req = WebRequest.Create("http://server/REST/IDs/Next");

        //etc., etc.
    }
}
share|improve this answer

If your comments are identical in both the interface and the class (which is what I am inferring if you don't know where to put the comments) then I would think that whatever comments you have are going to be the proverbial useless comments that people always gripe about. However, I wouldn't recommend not commenting one or the other. I would recommend putting meaningful comments in both classes instead. Surely there are meaningful differences between the interface and how the concrete class actually chose to implement the interface that are worth noting.

share|improve this answer

Put the documentation on the interface.

Why?

Just consider users of your class. They are coding against the interface, not the concrete class, so if you have no comments on the interface, they won't see them.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.