¿Cuáles son las ventajas de utilizar los comentarios XML en .NET?

Question

No puede entender las virtudes del uso de los comentarios XML. Sé que pueden ser convertidos en documentación externa agradable al código, pero lo mismo se puede lograr con la sintaxis Doxygen mucho más concisa. En mi opinión los comentarios XML están equivocados, ya que:

1. Se ofuscar los comentarios y el código en general. (Son más difíciles de leer por los humanos).
2. Menos código se puede ver en una sola pantalla, porque "Resumen" y "/ sumario" toman líneas adicionales.
3. (eliminado)

Entonces, ¿qué podría haber sido ser las razones, por qué se prefiere XML en .NET en lugar de que la sintaxis sencilla Doxygen?

Answer 1

En realidad no hay una respuesta correcta aquí imo. Ninguno de estos sistemas es "mejor" que el otro en la realidad -. Ambos hacen el mismo trabajo en el final, que es le permiten generar documentación de código

El resultado final puede ser formateado exactamente de la misma manera para cada uno de ellos, y tienen más o menos la misma funcionalidad en términos de lo etiquetas etc apoyan, así que es realmente reduce a una elección personal aquí.

Personalmente, creemos que los comentarios XML a ser mucho más legible, mucho más lógica y simplemente fácil de usar - pero eso es con la ventaja añadida de tener Visual Studio genera automáticamente talones para mí que rellene, y el excelente apoyo que tiene para el colapso de ellos para que no ocupan mucho espacio en la pantalla. Estoy seguro de que alguien que viene de un fondo de edición en el VI o some_other_IDE tendrá una opinión diferente, pero no hay ninguna ventaja real a cualquiera.

Así que yo diría que realmente depende de lo IDE que está utilizando y lo que usted y su equipo están acostumbrados a utilizar.

Ahora bien, si usted está preguntando por qué Microsoft ha optado por integrar tan estrechamente con XML comentando dentro de Visual Studio, que es una cuestión diferente. Lo más probable es que se debe a los siguientes hechos: que sería más sencillo para ellos para poner en práctica dentro de VS (ya que pueden reutilizar el código existente para generar / leer los comentarios y acumulación de IntelliSense etc), tienen una tendencia a pegarse a "normas "de todos modos (ya sea propio o de la industria queridos), y también la concesión de licencias razones mencionadas por Jeff.

Sólo para añadir que el producto Microsoft está utilizando dentro de VS se llama "Castillo de arena", que es una herramienta de generación de XML doc en el local. Tiene su propia página wiki @ http://docproject.codeplex.com/Wikipage

Answer 2

1. Las selecciones ide hasta los comentarios y los muestra cuando se utiliza ese método.
2. Todo el que los programas de C # es probablemente está familiarizado con el sistema de comentarios XML. Hay menos de aprender para un nuevo empleado.

No estoy diciendo que no Doxygen es mejor, es sólo que el sistema de comentarios XML es más familiar para todos, y que va un largo camino. Es sólo una cosa menos de lo que tiene que entrenar a un nuevo empleado para hacerlo.

En cuanto a las variables dejando sin comentar. Lo que puede ser obvio para usted, no va a ser la de otra persona (o en las que 6 meses después).

Ok, ahora creo ver lo que está pidiendo.

1. ofuscar comentarios. El código de colores ayuda. Personalmente, puedo escanear rápidamente más allá del texto gris y sólo leer lo que está verde a menos que necesite para leer el texto XML. (En la configuración de mi por lo menos).

2. Tenemos monitores de gran tamaño por lo que tenemos más código en la pantalla en general. (Es más barato comprar un monitor de gran tamaño que a la gente de reacondicionamiento general). La otra cosa acerca de esto también, es que apuesto a que sólo se busca activamente en una función a la vez, por lo que si que se adapte a la totalidad de función en una página, es probable que no están sufriendo demasiado de no ver más código. Ahora bien, si las funciones son largas, entonces pude ver que ser un problema.

3. Nos puso a los comentarios de resumen en una sola línea cuando sea posible (suponiendo que no es muy grande). Que reduce el espacio utilizado.

4. No sé si Doxygen hace esto, pero se puede colapsar los comentarios por lo que están fuera del camino.

Answer 3

El trabajo principal de los documentos XML es no para generar la documentación. Es para proporcionar buena información IntelliSense para el cliente de su clase. Enviar el archivo .xml generado junto con su montaje.

Answer 4

Las virtudes de la utilización de los comentarios XML en .NET

Son compatibles de forma nativa por el compilador de C # y Visual Studio, que proporciona una única ubicación para documentar su API para su uso en forma impresa, en línea y la documentación IntelliSense.

Este artículo de la revista MSDN establece lo siguiente:

  

En cada proyecto, hay alguien que   no es feliz con la documentación.   Los jefes de equipo quieren más comentarios en   la fuente, escritores técnicos quieren   más información escrita sobre el   diseño del código, garantía de calidad quiere   para ver las especificaciones funcionales y   pronto. Si todos estos documentos son   de hecho por escrito, usted todavía tiene la   batalla de mantener todos ellos   sincronizada.

Mientras que el formato no es necesariamente ideal comentarios de la documentación XML proporcionan una rica sintaxis de tal manera que esto se puede lograr.

¿Por qué no apoyar Doxygen en C # en lugar?

En cuanto a por qué el sistema XML existente fue elegido sobre Doxygen, yo sospecho que esto se debe principalmente a Doxygen es liberado bajo la GPL lo que significaría el compilador de C # Visual Studio pero también necesidad para ser lanzado como tal - algo que Microsoft sin duda no quieren hacer teniendo en cuenta los términos href="http://en.wikipedia.org/wiki/GPL#Terms_and_conditions" rel="nofollow de la GPL .

Answer 5

lo que me parece aún más alucinante es la popularidad de la GhostDoc plugin. Si usted puede generar automáticamente un comentario basado en un nombre de método, ¿por qué tener el comentario en absoluto?

Steve Yegge dice que sobre comentando es el signo de un programador novato, que tiene un tiempo difícil no estar de acuerdo con él.

Answer 6

No Tienes para utilizarlos en sus proyectos.

Son a estándar que pasa a estar integrado en Visual Studio y si utiliza StyleCop que se pueden hacer cumplir. Así que esta es la virtud aquí.

Sin embargo, si usted decide que quiere usar Doxygen entonces no hay nada que nos impida. Sólo asegúrese de que usted es constante.