Comentarios XML: ¿Usar o No usar?

Question

Mis compañeros de trabajo rara vez (si alguna vez) usan comentarios XML cuando trabajan en nuestro software (no puedo decir que estoy mejor). Recientemente he visto los beneficios de usarlos, pero ¿realmente valen la pena si el código que están documentando está escrito claramente (variables expresivas / descriptivas / nombres de funciones, algunos comentarios en línea)?

¡Gracias!

Answer 1

Los comentarios XML son útiles para generar documentación. Si el código está escrito claramente, entonces no debería necesitar comentarios para ayudarlo a entender el código.

Sin embargo, los comentarios de documentación son útiles para el usuario de las clases porque (debería) contener una descripción de la funcionalidad de la clase o de los métodos, no una descripción del código.

Answer 2

Creo que los comentarios de código son muy importantes, especialmente en métodos y propiedades de cara al público. Las personas pueden tener buenas intenciones cuando dicen que su código es descriptivo y tal vez lo es, pero piense en el nuevo tipo que mira esto:

Linker.Extract(IpoValidator validator, MeanDexIndicator Indicator)

A menos que comprenda el contexto del método, es posible que no descubra su propósito. El problema principal que las personas parecen tener con los comentarios es que no son muy útiles. Esto se debe a que la gente escribe malos comentarios. Debes hablar de lo que está sucediendo, no de lo que es. Puedo ver que el método es un método de extracción, así que comentarios como:

 <Summary>Extracts The Fumble <\Summary>

Son un desperdicio de energía. Lo siguiente es mejor:

 <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>

¿Ves la diferencia?

Tiendo a usar solo resúmenes, parámetros y devoluciones, ya que todos se muestran en intellisense, todo lo demás, como comentarios, y puede ser una pérdida de tiempo, ya que no siempre se muestran.

En cuanto al tipo que se niega a actualizar sus comentarios después de cambiar algo. Las revisiones de código deberían captar esto. Personalmente utilizo comentarios xml sobre métodos privados y accesorios dos, pero ese es una elección personal. ¿En métodos y propiedades de cara al público? I no es opcional.

Answer 3

Los comentarios XML son realmente útiles para las API, incluso los utilizados en un grupo pequeño.

Answer 4

Nos parece útil, porque vs verifica automáticamente para asegurarse de que haya ciertos comentarios. Además, cualquier persona que ingrese a la organización que haya utilizado vs antes sabe cómo funcionan los comentarios, y no tenemos que explicar un nuevo sistema de código de comentarios. En ocasiones, hemos generado documentación a partir de él, pero en realidad es más fácil para nosotros usarlo porque completa varias cosas para usted (como algunas etiquetas de parámetros, etc.)

Answer 5

En cuanto al código interno y los comentarios, aquí hay una publicación por Jeffery Palermo que acabo de leer y con el que estoy de acuerdo.

En resumen: muchos comentarios solo reducen la legibilidad y ayudan poco, los buenos comentarios pueden ser muy útiles, pero aumentan el costo para mantener el software e incluso pueden causar problemas importantes cuando no se mantienen y dan información falsa. No hay sustituto para el código bien diseñado y con nombre.

Answer 6

¿No hay una etiqueta de anotación que se ignore funcionalmente pero que pueda ser procesada por algún XSLT para convertirla directamente en documentación? Los comentarios son buenos (y los uso), pero creo que el valor de la etiqueta de anotación y la transformación directa pueden superar el uso del comentario como documentación. En resumen, use etiquetas de anotación para que otros lean la documentación, use comentarios para sus propias notas o cosas "detrás de escena" (es decir, "OMG ARREGLA ESTO ANTES DE QUE EL MUNDO EXPLOTE")