Come dovrebbero commenti per metodi di interfaccia e di classe essere diverso

Question

mi sono imbattuto in questo dilemma quando si lavora su un'applicazione web ASP.net utilizzando Web Client Software Factory (WCSF) in C #, e lo stesso potrebbe applicarsi ad altre piattaforme e le lingue. La mia situazione è simile a questo:

sto definendo un I Visualizza interfaccia per ciascun controllo della pagina web / utente in base WCSF paradigma, quindi hanno la classe di pagina di implementare l'I Visualizza interfaccia, in pratica attuazione ciascuno dei metodi definiti nell'interfaccia . Quando ho provato ad aggiungere xml-documentazione sul livello di metodo, mi sono ritrovato in fondo a ripetere lo stesso contenuto commento sia per metodo di interfaccia, e la sua contro-parte alla classe di implementazione.

Quindi la mia domanda è: ci dovrebbe essere qualche differenza sostanziale tra il contenuto della documentazione sul metodo di interfaccia e il corrispondente metodo della classe? Dovrebbero essere sottolineando il diverso aspetto o qualcosa del genere?

Qualcuno mi ha detto che il metodo di interfaccia commento dovrebbe dire "che cosa" il metodo dovrebbe fare, e il metodo della classe commento dovrebbe dire "come" lo fa. Ma mi ricordo di aver letto da qualche parte prima che il commento livello di metodo dovrebbe solo dire "che cosa" si suppone che il metodo per farlo, non il dettaglio di implementazione del metodo, in quanto l'attuazione non dovrebbe essere una preoccupazione per gli utenti di metodo e potrebbe cambiare.

Answer 1

Personalmente, penso che queste osservazioni dovrebbero essere gli stessi - entrambi dovrebbero dire "ciò che il metodo sta per fare", nei vostri termini

.

Non v'è alcun motivo di commenti XML per citare i dettagli di implementazione. L'unica eccezione, potenzialmente, potrebbe essere quella di parlare di potenziali effetti collaterali. (Vale a dire: questo metodo può richiedere molto tempo), ma io personalmente avrebbe fatto nella sezione <remarks> dei commenti di documentazione XML

Answer 2

Call me un dado ma mi piacerebbe utilizzare un nome descrittivo per il metodo e chiamare un giorno (nessun commento per entrambi). Potrei aggiungere commenti alla realizzazione se qualcosa al riguardo è sorprendente o perché la sua non c'è non ovvia.