Quelles sont les vertus de l'utilisation des commentaires XML dans .NET?

Question

Je ne comprends pas les vertus de l'utilisation des commentaires XML. Je sais qu'ils peuvent être convertis en bonne documentation externe au code, mais le même peut être réalisé avec la syntaxe doxygen beaucoup plus concise. À mon avis, les commentaires XML sont erronés, parce que:

1. Ils les commentaires et obscurcir le code en général. (Ils sont plus difficiles à lire par les humains).
2. Moins de code peut être consulté sur un seul écran, parce que « sommaire » et « / sommaire » prendre des lignes supplémentaires.
3. (supprimé)

Ce qui pourrait alors avoir été être les raisons, pourquoi XML a été préféré dans .NET plutôt que la syntaxe simple Doxygen?

Answer 1

Il n'y a pas vraiment une bonne réponse ici imo. Ni le système est « meilleur » que l'autre dans la réalité -. Ils ont tous deux font le même travail à la fin, ce qui est vous permettre de générer la documentation du code

La sortie finale peut être formaté exactement de la même façon pour chacun d'eux, et ils ont à peu près les mêmes fonctionnalités en termes de ce que les étiquettes, etc ils soutiennent, de sorte que son vraiment un choix personnel ici.

Personnellement, je trouve des commentaires XML beaucoup plus lisible par l'homme, beaucoup plus logique et tout simplement facile à utiliser - mais qui est avec l'avantage supplémentaire d'avoir visual studio générer automatiquement des talons pour moi de remplir juste et l'excellent soutien il a pour les effondrer afin qu'ils ne prennent pas beaucoup d'espace sur l'écran. Je suis sûr que quelqu'un qui vient d'une édition d'arrière-plan VI ou some_other_IDE aura un avis différent, mais il n'y a pas de réel avantage non plus.

Je dirais donc que vraiment cela dépend de ce que l'IDE que vous utilisez et ce que vous et votre équipe sont habitués à utiliser.

Maintenant, si vous demandez pourquoi Microsoft a choisi d'intégrer si étroitement avec XML des commentaires de Visual Studio, qui est une autre question. Très probablement, il est dû aux faits que: il serait plus simple pour eux de mettre en œuvre au sein de VS (car ils peuvent réutiliser le code existant pour générer / lire les commentaires et construire IntelliSense, etc.), ils ont tendance à coller aux « normes «de toute façon (que ce soit leurs propres ou ceux de l'industrie) et licences a aussi des raisons mentionnées par Jeff.

Il suffit d'ajouter que le produit Microsoft utilise dans les VS est appelé « Sandcastle », qui est un outil interne XML de génération de doc. Il a sa propre page wiki @ http://docproject.codeplex.com/Wikipage

Answer 2

1. Ide reprend les commentaires et les montre lors de l'utilisation de cette méthode.
2. Tous ceux qui ont des programmes C # est probablement familier avec le système de commentaires XML. Il y a moins d'apprendre une nouvelle location.

Je ne dis pas que Doxygen est pas mieux, il est juste que le système de commentaires xml est plus familier à tout le monde, et qui va un long chemin. Il est juste une chose de moins vous devez former une nouvelle location à faire.

En ce qui concerne les variables laissant décommentée. Ce qui peut être évident pour vous, ne sera pas à quelqu'un d'autre (ou pour vous 6 mois plus tard).

Ok maintenant je pense que je vois ce que vous demandez.

1. Dissimuler commentaires. Le code couleur aide. Personnellement, je scanne rapidement passé le texte gris et lu que ce qui est vert, à moins que je dois lire le texte XML. (Dans mes paramètres au moins).

2. Nous avons de grands écrans pour que nous obtenons plus de code à l'écran en général. (Il est moins cher d'acheter un grand écran que de reconvertir les gens en général). L'autre chose à ce sujet aussi, est que je parie que vous ne cherchez activement à une fonction à la fois, donc si cette fonction correspond à l'ensemble sur une page, vous n'êtes probablement pas trop souffrir de ne pas voir plus de code. Maintenant, si les fonctions sont longues, je pouvais voir que d'être un problème.

3. Nous avons mis les commentaires sommaires sur une seule ligne lorsque cela est possible (en supposant qu'il est pas vraiment grand). Cela permet de réduire l'espace utilisé.

4. Je ne sais pas si Doxygen fait cela, mais vous pouvez réduire les commentaires de sorte qu'ils sont hors de la voie.

Answer 3

La tâche principale de documentation XML est pas pour générer la documentation. Il est de fournir de bonnes informations IntelliSense pour le client de votre classe. Expédier le fichier .xml généré avec l'assemblage.

Answer 4

Les vertus de l'utilisation des commentaires XML dans .NET

Ils sont pris en charge nativement par le compilateur C # et Visual Studio, fournissant un emplacement unique pour documenter votre API pour en imprimé, en ligne et de la documentation IntelliSense.

Cet article du magazine MSDN stipule ce qui suit:

  

Dans chaque projet, il y a quelqu'un qui   est pas satisfait de la documentation.   Les chefs d'équipe veulent plus de commentaires en   la source, les rédacteurs techniques veulent   plus d'informations écrites sur le   conception de code, l'assurance qualité veut   pour voir les spécifications fonctionnelles et   bientôt. Si tous ces documents sont   en fait écrit, vous avez toujours la   bataille de garder tous   synchronisée.

Bien que le format est pas nécessairement idéal, les commentaires de documentation XML fournissent une syntaxe riche telle que cela peut être réalisé.

Pourquoi ne pas soutenir Doxygen en C # à la place?

Quant à savoir pourquoi le système XML existant a été choisi sur Doxygen, je soupçonne que ce principalement parce que Doxygen est libéré sous la GPL qui signifie Visual studio et le compilateur C # aurait également besoin à libérer en tant que tel - quelque chose que Microsoft ne voudrait sans doute pas faire en tenant compte des de la GPL .

Answer 5

ce que je trouve encore plus hallucinant est la popularité du GhostDoc plugin. Si vous pouvez générer automatiquement un commentaire basé sur un nom de méthode, pourquoi avoir le commentaire du tout?

Steve Yegge dit que sur des commentaires est le signe d'un programmeur débutant, j'ai du mal à être en désaccord avec lui.

Answer 6

Vous ne faites pas Vous pour les utiliser dans vos projets.

Ils sont a standard qui arrive à être intégré dans Visual Studio et si vous utilisez StyleCop ils peuvent être appliqués. C'est donc la vertu ici.

Cependant, si vous décidez d'utiliser Doxygen alors il n'y a rien qui vous empêche. Assurez-vous que vous êtes cohérent.