En cualquier entorno profesional, es necesario documentar adecuadamente su código con comentarios para lograr una legibilidad a largo plazo. Para el código .NET, Microsoft proporciona un sistema para comentarios basados en XML que proporciona soporte IDE mejorado.
Básicamente, los comentarios XML son un tipo especial de comentario indicado con una barra triple (
) y etiquetas XML para darle cierta estructura al comentario. Por ejemplo, un comentario de resumen simple sería similar al siguiente:
El punto de esto es que cuando vaya a utilizar este método en otra parte de su código, Visual Studio puede mirar el XML y agregar información directamente en la ventana emergente de Intellisense. Este sistema funciona para todo tipo de tipos e incluso se puede utilizar para documentar valores de retorno y parámetros individuales. Y, cuando distribuye el ensamblado, puede distribuir el archivo XML con él para habilitar estas mismas características para cualquiera que use su biblioteca de clases. Esto también permite un uso sencillo de generadores de documentación estática como DocFX y Castillo de arena.
Sorprendentemente, esta característica es principalmente una cuestión de .NET. Nada le impide utilizar la práctica con otros idiomas, pero es algo que Microsoft admite bien para sus idiomas y editores, y otros idiomas generalmente no tienen el soporte adecuado. Nos encantaría ver que el soporte para esto se expanda a otros idiomas y editores, ya que es bastante útil universalmente.
Es muy sencillo de utilizar. Simplemente presione la tecla de barra tres veces (
) encima de un método, clase u otro tipo, y Visual Studio insertará una plantilla para que usted la escriba. Esto le ahorra la molestia de escribirla manualmente, lo que significa que realmente no hay razón para no usarlos en lugar de los tradicionales comentarios de doble barra. .
Si su método tiene un tipo de retorno o parámetros, Visual Studio también generará campos para ellos. Verás tus comentarios cuando vayas a utilizar el método:
El estándar admite muchos tipos de etiquetas:
-
se muestra en Intellisense cada vez que utiliza el método. -
es como un resumen, pero no se muestra en Intellisense (útil para escribir documentación extendida). -
documenta el tipo de devolución. -
permite a los desarrolladores saber qué excepciones puede generar el método. -
es como devoluciones pero para propiedades de clase. -
muestra un ejemplo de código para la documentación (úselo con ). -
y generar enlaces en los que se puede hacer clic a otros métodos, generalmente utilizados para documentar sobrecargas. -
permite utilizar listas para ordenar elementos.
Puedes leer Documentación de Microsoft sobre el estándar de comentarios XML para más información.
