Method-Level-Dokumentation in n-Tier-Anwendungen

Question

Meine Situation:

Die Datenanforderung Kette meiner Anwendung sieht wie folgt aus:

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

Der Client ist eine Silverlight-Anwendung, die eine generierte Proxy verwendet zu kommunizieren mit einem WCF Webservice. Die wiederum Autorisierung und Zugriff auf SQL-DBs und OLAP-Cubes mit einer DAL-Komponente, im Grunde leitet es nur die Anforderungen. Daher besteht jede Methode an vier verschiedenen Orten:

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

Nun meine Frage, wo soll ich Dokumentation klar gestellt, um diese Methoden angeben? Auf Klassen- oder Schnittstellenebene, auf der DAL oder auf dem Webservice?

Meine Gedanken so weit:

Ich würde sagen, dass es am sinnvollsten ist die Methode Daten auf der Schnittstelle zu schreiben, denn es ist der Vertrag, der verbraucht wird. Allerdings habe ich nicht einen Vorteil zwischen webservice und DAL in meiner besonderen Situation sehen:

• Ich bin der einzige Entwickler, gibt es keine separaten Webservice-Typ oder Client-Typ, der die Dokumentation benötigt
• Dies ist ein geschlossene Architektur, die WebService nicht öffentlich ist
• Jeder an diesem Projekt in der Zukunft arbeiten, Zugang zu allen Komponenten davon haben werden (und wird die Dokumentation finden, wo immer sie sind)

Also, was tun Sie Denk darüber nach? Wo sollte ich Dokumentation auf Methodenebene in diesem Fall platzieren?

Answer 1

Ich würde denken, dass die meisten Leute erwarten würden, dass ein Web-Service stärker dokumentiert wird als ein DAL (besonders wenn der DAL meistens generierter Code ist: Ich vermute, das sind Pass-Through-Methoden). Ich würde einen Zeiger auf die Web-Service-Dokumentation in den DAL-Kommentaren für diejenigen, die damit in der Zukunft arbeiten, hinzufügen.

Der Grund ist zweifach. Erstens ist der Web Service der eigentliche Interaktionspunkt (und somit der Punkt, an dem mehr Clients hinzugefügt werden können, was bedeutet, dass der dokumentierte Service ein Plus ist). Die zweite ist, dass die DAL wirklich nicht so klingt, als ob sie über den Web Service "Mehrwert" bietet (in der beschriebenen Konfiguration), so dass es sinnvoll ist, auf den realen Punkt der Interaktion und des Werts zurückzukommen.

Wenn die DAL wurde jemals mit Wiederverwendung von einem anderen Client ohne die Web-Service-Layer bedroht ... ändert offensichtlich, dass die Dinge in die andere Richtung zu lehnen um (oder doppelte Kommentare zu automatisieren).