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:

/// <summary>
/// Dispara el evento <see cref="E:PagerChanged" />.
/// </summary>
/// <param name="e">The <see cref="System.EventArgs" /> instance containing the event data.
protected virtual void OnPagerChanged(EventArgs e)

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