Documentation au niveau de la méthode dans les applications à plusieurs niveaux

Question

Ma situation:

La chaîne de requête de données de mon application se présente comme suit:

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

Le client est une application Silverlight qui utilise un proxy généré pour communiquer avec un service Web WCF. Celui-ci, à son tour, autorise et accède aux bases de données SQL et aux cubes OLAP à l’aide d’un composant DAL, il ne fait que transmettre les demandes. Chaque méthode existe donc à quatre endroits différents:

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

Maintenant ma question, où devrais-je mettre la documentation pour spécifier clairement ces méthodes? Au niveau de la classe ou de l’interface, sur le DAL ou sur le service Web?

Mes pensées jusqu'à présent:

Je dirais qu'il est plus logique d'écrire les spécifications de la méthode sur l'interface, car c'est le contrat qui est consommé. Cependant, je ne vois pas d'avantage entre webservice et DAL dans ma situation spécifique:

• Je suis le seul développeur. Aucun type de service Web ou client-client distinct n'a besoin de la documentation
• Ceci est une architecture fermée, le service Web n'est pas public
• Toutes les personnes travaillant sur ce projet à l'avenir auront accès à toutes les composantes de celui-ci (et trouveront les documents, où qu'ils soient)

Alors, qu'en pensez-vous? Où devrais-je placer la documentation au niveau de la méthode dans ce cas?

Answer 1

Je pense que la plupart des gens s’attendraient à ce qu’un service Web soit plus documenté qu’un DAL (en particulier si le DAL est principalement du code généré: j’imagine qu’il s’agit de méthodes de transfert). J'ajouterais un pointeur sur la documentation du service Web dans les commentaires de la DAL pour ceux qui l'utilisent à l'avenir.

La raison est double. Premièrement, le service Web est le véritable point d’interaction (et donc le point où davantage de clients pourraient être ajoutés, ce qui signifie qu’avoir le service documenté est un atout). La seconde est que le DAL ne sonne pas vraiment comme une "valeur ajoutée". sur le service Web (dans la configuration décrite), il est donc logique de renvoyer au point d’interaction réel et à la valeur.

Si le DAL a été menacé de réutilisation par un autre client sans la couche de service Web ... cela change évidemment les choses pour simplifier les choses (ou pour automatiser les commentaires en double).