Comentarios XML en .NET

Todos sabemos que es una buena costumbre tener todo nuestro código bien documentado no solo para nosotros mismos sino para que cuando el código tenga que ser leído por otra persona le sea claro desde el primer momento. Pero, también sabemos que hacer comentarios en el código aburre (algunos consideramos que nos desconcentra del flujo del programa) y ni que hablar de los comentarios XML donde uno tiene que estar recordando las etiquetas necesarias lo cual nos hace perder tiempo y productividad a la hora de programar. En algún momento me construí mi propia herramienta (usando Macros) para documentar código basado en este artículo que me fue súper útil: Handy .NET Macro.

Menos mal que que existen herramientas para asistirnos en la laboriosa tarea de escribir nuestros amados comentarios XML, sí esos que hay que comenzar con “/// “.

En mi afán de tener una herramienta que documente código ya escrito encontré GhostDoc, que me ha servidor para resolver todas las necesidades que tenía para documentar el código. Veamos algunas características.

GhostDoc

GhostDoc es un plug-in compatible tanto con las versiones de Visual Studio 2005  y superiores creado por Roland Weigelt, cuya utilidad es (Obligarnos a escribir comentarios), automatizar la escritura de comentarios XML, generando toda la estructura del comentario, lo único que tenemos que hacer es modificar el texto que necesitemos para que todo sea más entendible y legible entre todos los programadores que comparten un proyecto.  Gracias a este plug-in nos ahorramos de escribir una cantidad impresionantes de texto y podemos realizar los comentarios XML muy rápido.

¿Cómo Funciona?

Muy simple, imaginemos que tenemos unas reglas de negocio complejas y que para ello tenemos que implementar algunas clases (aquí un ejemplo simple) :

Teniendo el código así se ve todo complejo y por lo tanto casi imposible de usar si es que no se tiene la documentación de:

• ¿Para qué sirve la clase?

• ¿Para qué sirve cada método?

• ¿Que representa cada parámetro?

Para proceder con nuestra tarea de documentación asistida tenemos que realizar los siguientes pasos:

1. Descargar la versión que corresponda de GhostDoc de la siguiente dirección:Roland Weigelt’s  GhostDoc. Luego procedemos a instalarlo dejando los valores por defecto.

2. Al iniciar Visual Studio se nos pedirá que seleccionemos algunas opciones como combinación de teclas para acceso directo, donde también pueden dejar los valores por defecto, para verificar que esté instalado el plug-in, revisar en el menú principal la opción “Tools”, bajo la que ahora debería estar GhostDoc.

3. Ya tenemos todo listo así que nos queda comenzar a generar los comentarios XML, en primer lugar comentaremos la clase, para lo cual pulsamos clic derecho sobre el nombre de la clase y en el menú contextual seleccionamos: “Document this” (también podemos utilizar la combinación de teclas de acceso rápido, si es que dejaron los valores por defecto serán: Ctrl + Shift + D)

   

   Esto genera la estructura del comentario completa incluida las etiquetas de resumen, poniendo el cursor en posición para escribir la descripción de la clase.

4. A continuación solo nos queda escribir la descripción de la clase:

   

5. Ahora nos toca generar los comentarios XML para los métodos, el proceso es el mismo, pulsamos clic derecho sobre el nombre del método y del menú contextual seleccionamos: “Document this”, lo cual genera toda la estructura necesaria para la descripción del método los parámetros de entrada y la salida del método. Ahora solo nos queda escribir la descripción del método, los parámetros y el valor de salida, repetimos el procedimiento para todos los métodos.

   

6. Ahora ya tenemos nuestra clase completamente comentada, cabe aclarar que en este caso solo utilizamos comentarios para la clase y para métodos, pero también se pueden generar comentarios para otros miembros de clases como propiedades y eventos. GhostDoc también tiene numerosas opciones de configuración avanzadas, para las cuales tendrán que profundizar más en el estudio de esta herramienta.

¿Y para qué sirven esos comentarios XML?
Ahora ya tenemos nuestra clase completamente comentada, y ¿para qué nos sirve esto?, pues si pensamos en lo más inmediato, sirve para que las personas que revisen el código de esta clase puedan guiarse por estos comentarios y entender la funcionalidad de los miembros de la clase, esta no es su única utilidad, también sirve para que los usuarios de nuestra clase sepan cómo utilizar los miembros públicos de la clase, los comentarios XML que escribimos se presentarán como ayudas de IntelliSense al momento de escribir el código como se muestra en las siguiente imagen:

La utilidad de los comentarios XML no termina aquí, también pude servir para generar los archivos de ayuda a partir de estos comentarios XML (pero esto merece otro artículo).
Espero que esta excelente herramienta os motive a escribir más comentarios XML y os sea de utilidad.