web-dev-qa-db-fra.com

Commenter l'interface, la mise en œuvre ou les deux?

J'imagine que nous tous (quand nous pouvons être dérangés!) Commentons 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 la mise en œuvre (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

c#javacommentsinterface
108
ng5000

En règle générale, j'utilise le même principe DRY (ne vous répétez pas) que pour le code:

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

Java spécifique: lorsque vous documentez l'implémentation, utilisez la balise {@inheritDoc} pour "inclure" les javadocs à partir de l'interface.

Pour plus d'informations:

87
Neeme Praks

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" dans la méthode.

7
NikolaiDante

Pour C #, cela dépend de l’OMI: Si vous utilisez des implémentations d’interfaces explicites, je ne les documenterais pas.

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é le document Cette commande au raccourci Ctrl + Maj + D et à l'une des frappes 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.

4
grover

Nous ne faisons que commenter l'interface. Les commentaires sont si faciles à désynchroniser avec la classe/interface dérivée ou de base.

Bien qu'il semble que @Nath suggère peut-être un outil de documentation automatisé qui aide à garder les choses ensemble (ça sonne bien si vous l'utilisez). Ici à WhereIWorkAndYouDontCare, les commentaires sont pour dev, donc un emplacement unique dans le code est préféré.

4
Jiminy

L'interface seulement. La duplication des commentaires est un doublon et il est probable que les deux jeux de commentaires se désynchroniseront éventuellement si le code change. Commentez l'implémentation avec "implémente MyInterface" ... Un peu comme Doxygen générera quand même des documents qui incluent les documents dérivés dans les documents de l'implémentation (si vous les configurez correctement).

3
Len Holgate

Commenter l'interface devrait être une documentation suffisante pour comprendre comment utiliser l'implémentation réelle. La seule fois où j'ajouterais des commentaires à la mise en œuvre, c'est si des fonctions privées ont été insérées pour satisfaire l'interface. Toutefois, il s'agirait uniquement de commentaires internes et ne figureraient pas dans la documentation en ligne ni 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.

2
X-Istence

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 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 à www.inheritdoc.io (version gratuite disponible).

0
K Johnson

Vous pouvez certainement commenter les deux, mais vous avez le problème du maintien des deux (comme mentionné précédemment). Cependant, à l’époque actuelle, aucun code consommateur n’utilisera vraiment IoC/DI et n’utilisera pas l’interface? Compte tenu de ce qui précède, si vous souhaitez seulement en commenter un, je vous suggère fortement de commenter l'interface. De cette façon, le consommateur de votre code obtiendra très probablement les astuces de Nice intellisense.

0
bytedev