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

Question

J'imagine que nous commentons tous (quand nous pouvons nous en donner la peine !) 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 c'est le cas, comment parvenez-vous à maintenir la synchronisation entre les deux ? Ou bien ajoutez-vous simplement un commentaire du type "Voir l'interface pour la documentation" ?

Merci

Answer 1

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

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

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

Pour plus d'informations :

• Documentation officielle de la javadoc
• Certains documents non officiels conseils .

Answer 2

Si vous utilisez le 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 "Documenter ceci" sur la méthode.

Answer 3

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

Answer 4

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

Cependant, si vous implémentez directement l'interface 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 associé la commande Document This au raccourci Ctrl+Shift+D et c'est l'une des touches que je presse presque automatiquement. Je crois que ReSharper a également la possibilité d'insérer la documentation de l'interface, lorsqu'il implémente les méthodes pour vous.

Answer 5

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

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