Verfahren Ebene 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, um mit einem WCF-Webservice zu kommunizieren. Was wiederum tut Autorisierung und greift SQL DB und OLAP-Cubes eine DAL-Komponente verwenden, im Grunde leitet sie nur die Anfragen. Daher ist jedes Verfahren in vier verschiedenen Stellen vorhanden ist:

// 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 stellen klar, diese Methoden angeben? Auf Klassen- oder Interface-Ebene, 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 keinen separaten Webservice-Typen oder Client-Typ ist, der die Dokumentation
braucht
• Dies ist eine geschlossene Architektur, die WebService nicht öffentlich
• Jeder an diesem Projekt in der Zukunft arbeitet, wird Zugang zu allen Komponenten davon hat (und die Dokumentation zu finden, wo immer sie sind)

Also, was denken Sie darüber? Wo soll ich Methode Ebene Dokumentation in diesem Fall?

Answer 1

Ich würde denken, dass die meisten Menschen ein Web-Service mehr zu dokumentieren stark als ein DAL erwarten würden (vor allem, wenn die DAL erzeugt wird meist Code: Ich vermute, so wie dies sind Pass-Through-Verfahren). Ich würde einen Zeiger auf die Web-Service-Dokumentation in den DAL Kommentaren für diejenigen hinzufügen, die in Zukunft mit ihm zu arbeiten.

Der Grund dafür ist eine doppelte. Erstens ist der Web-Service der eigentliche Punkt der Interaktion (und damit der Punkt, an dem mehr Kunden hinzugefügt werden können, was bedeutet, dokumentiert den Dienst hat, ist ein Plus). Die zweite ist, dass die DAL klingt nicht wirklich, wie es „Mehrwert“ über den Web Service (in der beschriebenen Konfiguration) bietet, so zeigt zurück auf die eigentliche Punkt der Interaktion und Wert macht Sinn.

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