Comentarios XML con GhostDoc en C#

Ya sé, no tienen que decírmelo, hacer comentarios en el código aburre 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 (Excelente excusa, espero que me lo crea mi jefa).

El único problema es que existen herramientas para asistirnos en la laboriosa tarea de escribir nuestros amados comentarios XML, sí esos que hay que comenzar con “/// “. Una de esas herramientas se denomina como ya habrán adivinado GhostDoc, la existencia de este tipo de herramientas tira por los suelos nuestras mejores excusas para no escribir comentarios.

Bueno ahora que no tenemos más excusas nos vemos obligados a ver cuál es la funcionalidad de esta herramienta.

GhostDoc
 GhostDoc es un plug-in compatible tanto con Visual Studio 2005  y Visual Studio 2008 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 esté más entendible, gracias a este plug-in nos ahorramos de escribir una cantidad impresionantes de texto y podemos realizar los comentarios XML muy rápido; repito ahora ya no hay excusas.

¿Cómo Funciona?
La mejor manera para comprender su funcionamiento es con un pequeño ejemplo, donde mostraremos su utilidad. Asumamos que estamos escribiendo un sistema altamente complejo donde tenemos que implementar la clase calculadora de la siguiente manera:

ClaseCalculadora

Como verán es una clase muy compleja 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) 

    MenuContextual

    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:

    ComentarioClaseGenerado

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

    ComentarioClaseEscrito

  4. 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, como se muestra en la siguiente figura:

    ComentarioMetodoGenerado

    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.

     ComentarioMetodoEscrito

  5. 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 la clase “Calculadora”  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 “Calculadora” 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 siguientes figuras:

 IntelliSenseMetodo

 IntelliSenseParametros

La utilidad de los comentarios XML no termina aquí, en el siguiente artículo veremos cómo generar los archivos de ayuda a partir de estos comentarios XML.
Espero que esta excelente herramienta los motive a escribir más comentarios XML.

Enlaces
Página Oficial de GhostDoc: Roland Weigelt’s  GhostDoc

1 comment so far

  1. Sergi on

    Hola,

    he posteado en http://interbuilders.blogspot.com/2008/10/configuracin-de-ghostdoc-en-castellano.html una configuración de ghostDoc en castellano, por si a alguien le interesa.

    Saludos!


Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión / Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión / Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión / Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión / Cambiar )

Conectando a %s

A %d blogueros les gusta esto: