Documentazione a livello di metodo in applicazioni di livello n

Question

La mia situazione:

La catena di richiesta dati della mia applicazione è simile alla seguente:

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

Il client è un'applicazione Silverlight che utilizza un proxy generato per comunicare con un servizio web WCF. Il che a sua volta autorizza e accede ai cubi di SQL DB e OLAP utilizzando un componente DAL, sostanzialmente inoltra solo le richieste. Pertanto, ogni metodo esiste in quattro luoghi diversi:

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

Ora la mia domanda, dove devo mettere la documentazione per specificare chiaramente questi metodi? A livello di classe o di interfaccia, sul DAL o sul servizio web?

I miei pensieri finora:

Direi che ha molto senso scrivere le specifiche del metodo sull'interfaccia, perché è il contratto che viene consumato. Tuttavia non vedo un vantaggio tra webservice e DAL nella mia situazione specifica:

• Sono l'unico sviluppatore, non esiste un webservice-guy o client-guy separato che abbia bisogno dei documenti
• Questa è un'architettura chiusa, il servizio web non è pubblico
• Tutti coloro che lavorano su questo progetto in futuro, avranno accesso a tutti i suoi componenti (e troveranno i documenti, ovunque si trovino)

Allora, cosa ne pensi? Dove devo inserire la documentazione a livello di metodo in questo caso?

Answer 1

Penso che la maggior parte delle persone si aspetterebbe che un servizio web sia documentato più pesantemente di un DAL (specialmente se il DAL è per lo più codice generato: immagino che si tratti di metodi pass-through). Aggiungerei un puntatore alla documentazione del servizio Web nei commenti DAL per coloro che lavoreranno con esso in futuro.

Il motivo è duplice. Innanzitutto, il servizio Web è il vero punto di interazione (e quindi il punto in cui potrebbero essere aggiunti più client, il che significa che avere il servizio documentato è un vantaggio). Il secondo è che il DAL in realtà non suona come se fornisse " valore aggiunto " tramite il servizio Web (nella configurazione descritta), quindi ha senso tornare al reale punto di interazione e valore.

Se il DAL è mai stato minacciato di riutilizzo da parte di un altro client senza il livello del servizio Web ... ovviamente ciò cambia le cose per inclinarsi al contrario (o per automatizzare i commenti duplicati).