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