documentação de nível de método em aplicações n-tier

Question

Meu Situação:

A cadeia de solicitação de dados do meu aplicativo parecido com este:

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

O cliente é um aplicativo do Silverlight que usa um proxy gerado para se comunicar com um webservice WCF. Que por sua vez faz autorização e acessos de SQL DB e OLAP Cubes usando um componente DAL, basicamente é apenas encaminha as solicitações. Portanto, cada método existe em quatro lugares diferentes:

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

Agora a minha pergunta, onde devo colocar a documentação para especificar claramente esses métodos? Na classe ou nível de interface, na DAL ou no webservice?

Os meus pensamentos até agora:

Eu diria que faz mais sentido para escrever as especificações do método na interface, porque é o contrato que está sendo consumido. No entanto, não vejo uma vantagem entre webservice e DAL na minha situação específica:

• Eu sou o único desenvolvedor, não há separada webservice-cara ou cliente-cara que precisa dos docs
• Esta é uma arquitetura fechada, o webservice não é público
• Todos trabalhando neste projeto no futuro, terá acesso a todos os componentes do mesmo (e vai encontrar os docs, onde quer que estejam)

Então, o que você acha sobre isso? Onde devo colocar a documentação em nível de método neste caso?

Answer 1

Gostaria de pensar que a maioria das pessoas seria de esperar um serviço web para ser documentado mais fortemente do que uma DAL (especialmente se a DAL é principalmente gerado código: Eu estou supondo modo como estes são pass-through métodos). Gostaria de acrescentar um ponteiro para a documentação de serviço web nos comentários DAL para aqueles que trabalham com ele no futuro.

A razão é dupla. Primeiro, o serviço Web é o verdadeiro ponto de interação (e, portanto, o ponto em que pode ser adicionado mais clientes, o que significa ter o serviço documentado é um plus). A segunda é que o DAL realmente não soa como ele fornece "valor acrescentado" sobre o Serviço Web (na configuração descrita), então apontando para o verdadeiro ponto de interação e valor faz sentido.

Se o DAL já foi ameaçado de reutilização por outro cliente sem a camada de serviço web ... obviamente isso muda as coisas a inclinar-se o contrário (ou para automatizar comentários duplicados).