Commentez l'interface, l'implémentation ou les deux?

J'imagine que nous commentons tous (quand nous pouvons être dérangés!) Nos interfaces. par exemple

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

Commentez-vous également l'implémentation (qui peut également être fournie aux clients, par exemple dans le cadre d'une bibliothèque)? Si oui, comment gérez-vous la synchronisation des deux? Ou ajoutez-vous simplement un commentaire «Voir l'interface pour la documentation»?

Merci

En règle générale, j'utilise le même principe DRY (Don't Repeat Yourself) que pour le code:

• sur l'interface, documenter l'interface
• sur la mise en œuvre, documentez les spécificités de la mise en œuvre

Spécifique à Java : lors de la documentation de l'implémentation, utilisez la balise {@inheritDoc} pour "inclure" les javadocs de l'interface.

Pour plus d'informations:

• Documentation officielle javadoc
• Quelques conseils non officiels .

Si vous utilisez le complément GhostDoc, il met à jour l'implémentation avec le commentaire de l'interface lorsque vous cliquez avec le bouton droit de la souris et sélectionnez "Document This" sur la méthode.

Pour C #, cela dépend IMO: si vous utilisez des implémentations d'interface explicites, je ne documenterais pas l'implémentation.

Cependant, si vous implémentez l'interface directement et exposez les membres de l'interface avec votre objet, ces méthodes doivent également être documentées.

Comme Nath l'a dit, vous pouvez utiliser GhostDoc pour insérer automatiquement la documentation d'une interface dans l'implémentation. J'ai mappé la commande Document This au raccourci Ctrl + Shift + D et c'est l'une des touches sur lesquelles j'appuie presque automatiquement. Je pense que ReSharper a également la possibilité d'insérer la documentation de l'interface, lorsqu'il implémente les méthodes pour vous.

L'interface uniquement. Commenter les deux est une duplication et il est probable que les deux ensembles de commentaires finiront par se désynchroniser si le code change. Commentez l'implémentation avec "implements MyInterface" ... Des choses comme Doxygen généreront des documents qui incluent les documents dérivés dans les documents pour l'implémentation de toute façon (si vous les configurez correctement).

Nous commentons simplement l'interface, les commentaires sont si faciles à désynchroniser avec la classe / interface dérivée ou de base, c'est bien de l'avoir en un seul endroit.

Bien que cela ressemble à @Nath, peut-être suggérant un outil de documentation automatisé qui aide à garder les choses ensemble (cela semble cool si vous l'utilisez). Ici, à WhereIWorkAndYouDontCare, les commentaires sont pour les développeurs, donc un seul endroit dans le code est préférable

Commenter l'interface devrait être une documentation suffisante pour comprendre comment utiliser l'implémentation réelle. Le seul moment où j'ajouterais des commentaires à l'implémentation est si elle a des fonctions privées qui ont été insérées pour satisfaire l'interface, mais il s'agirait uniquement de commentaires internes et ne seraient pas visibles dans la documentation en ligne ou disponibles pour les clients.

Les implémentations ne sont que cela, tant qu'elles sont conformes à l'interface, il n'est pas nécessaire de les documenter séparément.

J'ai créé un outil qui post-traite les fichiers de documentation XML pour ajouter la prise en charge de la balise <inheritdoc />.

Bien que cela n'aide pas avec Intellisense dans le code source, il permet aux fichiers de documentation XML modifiés d'être inclus dans un package NuGet et fonctionne donc avec Intellisense dans les packages NuGet référencés.

C'est sur www.inheritdoc.io (version gratuite disponible).

Vous pouvez certainement commenter les deux, mais vous avez alors le problème de maintenir les deux (comme mentionné précédemment). Cependant, à l'heure actuelle, est-ce que tout code consommateur n'utilisera pas IoC / DI et n'utilisera pas l'interface? Compte tenu de cela, si vous ne souhaitez en commenter qu'un, je vous suggère fortement de commenter l'interface. De cette façon, le consommateur de votre code obtiendra plus que probablement les bons indices intelligents.

Utilisation C #:

L'interface peut ressembler à ceci:

    /// <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();
    }
}

La mise en œuvre peut ressembler à ceci:

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