Method-level documentation in n-Tier applications

Question

My Situation:

The data request chain of my application looks like this:

(Client) -> (WebService) -> (SQL or OLAP Cube)

The client is a Silverlight Application that uses a generated proxy to communicate with a WCF webservice. Which in turn does authorization and accesses SQL DB's and OLAP Cubes using a DAL component, basically it just forwards the requests. Therefore, each method exists in four different places:

// WCF Webservice interface and implementation (used by client)
public interface ICatalogService 
public class CatalogService : ICatalogService

// DAL interface and implementation (used by webservice)
public interface ICatalogDataAccessLayer
public class CatalogDataAccessLayer : ICatalogDataAccessLayer

Now my question, where should I put documentation to clearly specify these methods? On class or interface level, on the DAL or on the webservice?

My thoughts so far:

I would say it makes most sense to write the method specs on the interface, because it is the contract that is being consumed. However I don't see an advantage between webservice and DAL in my specific situation:

• I am the only developer, there is no separate webservice-guy or client-guy that needs the docs
• This is a closed architecture, the webservice is not public
• Everyone working on this project in the future, will have access to all components of it (and will find the docs, wherever they are)

So, what do you think about it? Where should I put method-level documentation in this case?

Answer 1

I would think that most people would expect a web service to be documented more heavily than a DAL (especially if the DAL is mostly generated code: I'm guessing so as these are pass-through methods). I would add a pointer to the web service documentation in the DAL comments for those who work with it in the future.

The reason is twofold. First, the Web Service is the real point of interaction (and thus the point where more clients might be added, which means having the service documented is a plus). The second is that the DAL really doesn't sound like it provides "added value" over the Web Service (in the configuration described), so pointing back to the real point of interaction and value makes sense.

If the DAL was ever threatened with reuse by another client without the web service layer... obviously that changes things to lean the other way around (or to automate duplicate comments).