Documentación básica de código

En este artículo veremos la documentación básica que podemos realizar en nuestros proyectos de .NET. Visual Studio nos permite colocar comentarios de documentación para nuestro código colocando etiquetas XML en el código fuente, justo antes del bloque de código al que hará referencia. Por ejemplo:

/// <summary>
/// Este método es realmente soberbio.
/// </summary>
public void MetodoDeEjemplo()
{
    //...código
}

Como todos los comentarios, sean o no de documentación, el compilador simplemente los ignora y por lo tanto no afecta al rendimiento de nuestra aplicación. Los comentarios aplican cobre clases, métodos, estructuras, delegados, interfaces, propiedades, campos, enumeraciones, eventos y muchos otros elementos.  Por ahora nos conformaremos con documentar clases/estructuras, métodos y propiedades (en los métodos se incluyen los constructores) y con los elementos más comunes y relevantes.

Comenzaremos con algo simple, una propiedad. Como mencioné arriba, basta con colocarnos inmediatamente antes de la declaración y poner tres diagonales (///); esta acción es detectada por el IntelligentSense y nos pone las etiquetas de <summary>, esta etiqueta es utilizada para poner una descripción de lo que estamos documentando (una propiedad en nuestro caso) y es usada por el IntelligentSense para mostrar la descripción al momento de estar escribiendo código. Veamos los resultados:

/// <summary>
/// Descripción de la propiedad
/// </summary>
public string Propiedad
{ get; set; }

Usando la propiedad obtenemos este resultado:

Podemos ver subrayado en rojo que el IntelligentSense nos muestra el texto que pusimos dentro de la etiqueta <summary>, de esta forma podemos tener una documentación en nuestro desarrollo y no tener que estar revisando el código para acordarmos lo que hace un método, qué significa cierta propiedad, etc. Esto también es muy util si desarrollamos un módulo que será usado por otras personas para otro desarrollo, nos ahorramos la molestia de que nos pregunten sobre lo que hace tal método, qué representa tal clase, etc.

<summary> es la etiqueta básica para la documentación, pero existen muchas otras. Ahora veamos otro ejemplo más completo con un método:

/// <summary>Este método suma dos enteros</summary>
/// <param name="a">Primer operando</param>
/// <param name="b">Segundo operando</param>
/// <returns>La suma de los operandos</returns>
public int Suma(int a, int b)
{ return a + b; }

De igual manera, al poner las tres diagonales(///) antes de la declaración del método, VisualStudio automáticamente nos coloca las etiquetas de <summary>,<param name=[nombreDelParametro]>, <returns>. Como podrán intuir, las dos etiquetas <param> hacen referencia a los dos parámetros requeridos en el método, y la etiqueta <returns> es para lo que regresa el método (VS no lo coloca cuando el método es void). Veamos el resultado:

Como podemos ver, el IntelligentSense nos muestra la descripción del método y en este caso también el texto que pusimos dentro de <param name="a">, que es el primer parámetro del método. Los mismo ocurre para el parámetro b cuando estemos situados en su posición [p.e. c.Suma(3,)].

Un punto que hay que mencionar es que no vemos nada acerca de lo que pusimos en <returns>. Esta etiqueta no es mostrada por el IntelligentSense, pero es utilizada por el Object Browser de VS; esto toma mucha relevancia cuando nuestro código esta compilado en una DLL y es agregada como referencia en otro proyecto, al usar el Object Browser podemos ver todo lo documentado en nuestra clase.

Y ahí tenemos nuestro texto que escribimos dentro de <returns>.

Además de estas tres etiquetas existen muchas otras (unas visibles para el IntelligentSense y otras no), pero todas nos ayudan para crear una buena documentación de nuestros desarrollos, además de que es posible crear archivos XML con la documentación y crear documentación técnica final usado herramientas como SandCastle. En próximas entregas se abordarán más etiquetas y el uso del SandCastle.

Agradeceré mucho sus comentarios y sugerencias, saludos...

Leonardo Landín

icolandin@gmail.com