Commentaires XML: utiliser ou ne pas utiliser?

Question

Mes collègues utilisent rarement (si jamais) des commentaires XML lorsqu'ils travaillent sur notre logiciel (je ne peux pas dire que je suis meilleur). J'ai récemment constaté les avantages de leur utilisation, mais valent-ils vraiment la peine si le code qu'ils documentent est écrit clairement (noms de variable / fonction descriptifs / descriptifs, commentaires en ligne, par exemple)?

Merci!

Answer 1

Les commentaires XML sont utiles pour générer de la documentation. Si le code est clairement écrit, vous ne devriez pas avoir besoin de commentaires pour vous aider à comprendre le code.

Cependant, les commentaires de la documentation sont utiles à l'utilisateur des classes car il (devrait) contenir une description de la fonctionnalité de la classe ou des méthodes, pas une description du code.

Answer 2

Je pense que les commentaires de code sont très importants, en particulier pour les méthodes et les propriétés destinées au public. Les gens peuvent bien vouloir dire quand ils disent que leur code est descriptif, peut-être, mais pensez au nouveau type qui regarde ça:

Linker.Extract(IpoValidator validator, MeanDexIndicator Indicator)

S'il ne comprend pas le contexte de la méthode, il risque de ne pas en déterminer le but. Le principal problème que les gens semblent avoir avec les commentaires est qu'ils ne sont pas très utiles. C'est parce que les gens écrivent de mauvais commentaires. Vous devriez parler de ce qui se passe et non de ce que c'est. Je peux voir que cette méthode est une méthode d'extraction, donc des commentaires comme:

 <Summary>Extracts The Fumble <\Summary>

sont un gaspillage d'énergie. Ce qui suit est mieux:

 <Summary>
 The Fumble needs to be extracted before the bopper can be used. In order for 
 extraction to work a validator and indicator need to be provided. Once extracted 
 the bopper is available in the property Linker.Bopper. On fail this 
 method will raise the CrappedOutException.
 </Summary>

Vous voyez la différence?

J'ai tendance à n'utiliser que des paramètres de résumé et des retours tels qu'ils apparaissent tous dans intellisense. Tout le reste est assimilable à des remarques et peut être une perte de temps, car ils ne sont pas toujours affichés.

En ce qui concerne le gars qui refuse de mettre à jour ses commentaires après avoir changé quelque chose. Les revues de code devraient attraper cela. Personnellement, j’utilise les commentaires XML sur les méthodes privées et les accessoires deux mais c’est un choix personnel. Sur les méthodes et les propriétés faisant face au public? I est non optionnel.

Answer 3

Les commentaires XML sont vraiment utiles pour les API, même celles utilisées dans un petit groupe.

Answer 4

Nous trouvons cela utile, car vs vérifie automatiquement que certains commentaires sont présents. De plus, quiconque entre dans l'organisation qui a déjà utilisé vs auparavant sait comment fonctionnent les commentaires et nous n'avons pas à expliquer un nouveau système de code de commentaire. Nous avons parfois généré de la documentation à partir de celle-ci, mais en réalité, son utilisation est plus simple car elle remplit plusieurs fonctions pour vous (comme certaines balises de paramètre, etc.)

Answer 5

Pour ce qui est du code et des commentaires internes, , voici un article par Jeffery Palermo que je viens de lire et sur lequel je suis d'accord.

En résumé: un grand nombre de commentaires ne fait que réduire la lisibilité et aide peu, de bons commentaires peuvent être très utiles, mais augmentent les coûts de maintenance du logiciel et peuvent même causer des problèmes majeurs s’ils ne sont pas maintenus et donnent de fausses informations. Rien ne remplace un code bien conçu et nommé.

Answer 6

N'y a-t-il pas une balise d'annotation qui est ignorée fonctionnellement mais qui peut être traitée par certains XSLT pour être transformée directement en documentation? Les commentaires sont bons (et je les utilise) mais je pense que la valeur de la balise d'annotation et sa transformation directe peuvent l'emporter sur l'utilisation du commentaire en tant que documentation. Donc, en résumé, utilisez des balises d’annotation pour que la documentation soit lue par d’autres personnes, utilisez des commentaires pour rédiger des notes personnelles ou faites des choses «en coulisse» (c’est-à-dire «OMG FIX CELA AVANT QUE LE MONDE EXPLOSE!»)