Commenta l'interfaccia, l'implementazione o entrambi?

Immagino che tutti (quando possiamo essere disturbati!) Commentiamo 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);
}

Commenta anche l'implementazione (che può anche essere fornita ai clienti, ad esempio come parte di una libreria)? In tal caso, come riesci a mantenere i due sincronizzati? O aggiungi semplicemente un commento "Vedi l'interfaccia per la documentazione"?

Grazie

Come regola generale, utilizzo lo stesso principio DRY (Don't Repeat Yourself) del codice:

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

Specifico per Java : quando si documenta l'implementazione, utilizzare il tag {@inheritDoc} per "includere" javadocs dall'interfaccia.

Per maggiori informazioni:

• Documentazione ufficiale javadoc
• Qualche consiglio non ufficiale .

Se si utilizza il componente aggiuntivo GhostDoc , aggiorna l'implementazione con il commento dall'interfaccia quando si fa clic con il pulsante destro del mouse e si seleziona "Document This" sul metodo.

Per C # dipende IMO: se usi implementazioni esplicite dell'interfaccia, non documenterei l'implementazione.

Tuttavia, se si implementa direttamente l'interfaccia e si espongono i membri dell'interfaccia con l'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 documento Questo comando sulla scorciatoia Ctrl + Maiusc + D ed è uno dei tasti premuti quasi automaticamente. Credo che ReSharper abbia anche la possibilità di inserire la documentazione dell'interfaccia, quando implementa i metodi per te.

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

Commentiamo semplicemente l'interfaccia, i commenti sono così facili da sincronizzare con la classe / interfaccia derivata o base che è bello averlo in un solo posto.

Anche se sembra che @Nath forse suggerisca uno strumento di documentazione automatizzata che aiuta a tenere le cose unite (suona bene se lo usi). Qui su WhereIWorkAndYouDontCare i commenti sono per dev, quindi è preferibile un singolo punto nel codice

Commentare l'interfaccia dovrebbe essere una documentazione sufficiente per capire come utilizzare l'implementazione effettiva. 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 clienti.

Le implementazioni sono solo che, purché conformi all'interfaccia, non è necessario documentarle separatamente.

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

Anche se non aiuta con Intellisense nel codice sorgente, consente di includere i file di documentazione XML modificati in un pacchetto NuGet e quindi funziona con Intellisense nei pacchetti NuGet di riferimento.

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

Puoi certamente commentare entrambi, ma poi hai il problema di mantenerli entrambi (come accennato in precedenza). Tuttavia, al giorno d'oggi un codice che consuma davvero non utilizzerà IoC / DI e non utilizzerà l'interfaccia? Dato questo, se vuoi solo disturbarti a commentarne uno, ti consiglio vivamente di commentare l'interfaccia. In questo modo il consumatore del tuo codice otterrà molto probabilmente i suggerimenti di intellisense.

C # utilizzo:

L'interfaccia può apparire così:

    /// <summary>
    /// Helper class to access various properties for the current site.
    /// </summary>
    public interface ISiteHelper
    {
        /// <summary>
        /// Gets the site id of the current site
        /// </summary>
        /// <returns>The site id.</returns>
        int GetSiteID();
    }
}

L'implementazione può apparire così:

/// <inheritdoc />
public class SiteHelper: ISiteHelper
{
    /// <inheritdoc />
    public int GetSiteID()
    {
        return CommonRepository.GetSiteID();
    }
}