En mi trabajo actual en Virtua como analista de aplicaciones y programador, estamos trabajando intensamente con Visual Studio 2008 para el desarrollo de una aplicación web en el ámbito del eLearning.

Uno de los requisitos que siempre nos ha exigido nuestro cliente era el de disponer de una buena documentación del código fuente (que en este caso les pertenece). En los viejos tiempos, cuando la tecnología era ASP, esto era, cuanto menos, imposible. Sin embargo, la migración a tecnología .NET nos pone las cosas un poco más fáciles, al disponer de comentarios XML mediante los que podemos documentar casi cualquier cosa, incluyendo su semántica (método, parámetro, evento, etc.), como en el siguiente ejemplo:

donde estamos documentando el método que dispara un evento y el parámetro que recibe (faltan los “GhostDoc. Un add-in para Visual Studio totalmente recomendable. GhostDoc amplía la funcionalidad de VS mediante el comando “Document this…” (Ctrl+Shift+D en la configuración por defecto), que nos añadirá automáticamente el comentario al miembro de la clase donde estemos y será capaz de introducir parte de la documentación, como los parámetros y sus tipos, a partir de unas reglas configurables de que dispone.

El único “pero” que se le podría poner es que está enfocado a generar documentación en inglés, y muchos de los textos que genera están “hard-coded” en el idioma de Shakespeare, cosa por otro lado lógica por el análisis que realiza de los nombres de los miembros que documentamos para inferir la documentación a partir de estos. Ah, y el soporte para VB es todavía experimental.

Sin embargo, otra parte de los textos se colocan directamente a través de las reglas que se definen en la configuración, y que hemos podido traducir nosotros mismos al castellano. Así sólo tenemos que modificar unos pocos textos de los que genera.

El archivo de configuración traducido al castellano se encuentra disponible aquí. Se incluyen también las modificaciones que publicó Roland en su blog para la documentación de los métodos override (toString, Equals y GetHashCode), también en castellano.

Cuando instaláis GhostDoc por primera vez, podéis importar este archivo de configuración en el mismo proceso de instalación.

Una vez tenemos todo nuestro código bien comentado, el siguiente proceso es generar la documentación… pero eso otra historia, y merece ser contada en otra ocasión. Pista: SandCastle

  • http://www.blogger.com/profile/06431861373242706630 ciderdead

    Hola..

    Estuve mirando el post.. me parecio muy interesante .. pero el archivo al que haces mencion ya no existe en la ruta que has dado…

    Podrias por favor corregir la ruta..

    Gracias

  • http://www.sergigisbert.com Sergi

    Hola,

    ya he corregido el enlace. Cosas de cambiar de sistema operativo: el nuevo IIS ha decidido no servir los archivos .gdc.

    Lo he renombrado a .xml, así que cámbiale la extensión al descargarlo, aunque es probable que GhostDoc lo importe igualmente.

    Gracias por la corrección!

  • http://www.blogger.com/profile/00790347426467562713 Elkin Jose Vasquez Isenia

    Hola Sergio, el archivo no funciona correctamente cuando lo cargo me arroja error.