Commenta l'interfaccia, l'implementazione o entrambi?

Question

Immagino che tutti (quando possiamo essere infastiditi!) Commentino le nostre interfacce. per esempio.

/// <summary> 
/// Foo Interface 
/// </summary> 
public interface Foo 
{ 
    /// <summary> 
    /// Will 'bar' 
    /// </summary> 
    /// <param name="wibble">Wibble factor</param> 
    void Bar(string wibble); 
} 

si fa a commentare anche l'attuazione (che può anche essere forniti ai clienti, ad esempio, come parte di una una biblioteca)? Se sì, come gestisci mantenendo i due sincronizzati? O semplicemente aggiungi un commento "Vedi l'interfaccia per la documentazione"?

Grazie

Answer 1

Come regola generale, io uso lo stesso DRY (Do not Repeat Yourself) principio con il codice:

• su l'interfaccia, l'interfaccia di documentare
• sull'attuazione, documentare le specifiche di implementazione

Java specifico: quando documenta la realizzazione, utilizzare {} @inheritDoc tag "include" javadocs f rom l'interfaccia.

Per maggiori informazioni:

• Official javadoc documentation
• Alcuni non ufficiale advice.

Answer 2

Se si utilizza il componente aggiuntivo GhostDoc, aggiorna l'applicazione con il commento dall'interfaccia quando si fa clic destro e selezionare "Documento Questa" sul metodo.

Answer 3

Commentando l'interfaccia dovrebbe essere sufficiente documentazione per capire come utilizzare l'implementazione reale. L'unica volta che aggiungerei commenti all'implementazione è se ha funzioni private che sono state inserite per soddisfare l'interfaccia, tuttavia sarebbero solo commenti interni e non verrebbero visualizzati nella documentazione online o disponibili per i client.

Le implementazioni sono proprio così, a patto che siano conformi all'interfaccia non è necessario documentarle separatamente.

Answer 4

Solo l'interfaccia. Commentare entrambi è duplicazione ed è probabile che i due gruppi di commenti finiranno per non essere sincronizzati se il codice cambia. Commenta l'implementazione con "implementa MyInterface" ... Cose come Doxygen generano documenti che includono i documenti derivati ​​nei documenti per l'implementazione comunque (se li hai impostati correttamente).

Answer 5

Per C# dipende IMO: Se si utilizzano implementazioni di interfaccia esplicite, quindi non documenterei l'implementazione.

Tuttavia, se si implementa direttamente l'interfaccia e si espongono i membri dell'interfaccia con il proprio oggetto, anche questi metodi devono essere documentati.

Come ha detto Nath, è possibile utilizzare GhostDoc per inserire automaticamente la documentazione di un'interfaccia nell'implementazione. Ho mappato il comando Documento con la scorciatoia Ctrl + Maiusc + D e il tasto uno dei tasti premo quasi automaticamente. Credo che ReSharper abbia anche la possibilità di inserire la documentazione dell'interfaccia, quando implementa i metodi per te.

Answer 6

Abbiamo solo commentato l'interfaccia, i commenti sono così facili da non sincronizzare con la classe derivata o l'interfaccia di base che è bello averlo in un solo posto.

Anche se sembra che @Nath suggerisca forse uno strumento di documentazione automatizzato che aiuti a tenere insieme le cose (sembra fantastico se lo si utilizza). Qui a WhereIWorkAndYouDontCare i commenti sono per dev così un unico posto nel codice è preferito

Answer 7

Ho creato uno strumento che post-elabora i file di documentazione XML per aggiungere il supporto per il tag < inheritdoc/>.

Sebbene non sia d'aiuto con Intellisense nel codice sorgente, consente di includere i file di documentazione XML modificati in un pacchetto NuGet e pertanto funziona con Intellisense nei pacchetti NuGet referenziati.

È disponibile su www.inheritdoc.io (versione gratuita disponibile).