lunes, 4 de junio de 2007

Comentando C# con XML

Krlo [blackhat4all@gmail.com]

Aunque muchos de nosotros no acostumbramos a comentar nuestro código, porque creemos que no vale la pena o nos dejamos arrastrar por la haraganería, estamos conscientes que un programa no comentado es un problema colosal a la hora del mantenimiento. En Microsoft, se refieren a comentar como una Best Practice para el desarrollo de cualquier tipo de aplicación. Por tal motivo, el lenguaje insignia de su plataforma .NET incorpora desde su primera versión en Visual Studio .NET 2003, la facilidad de que su IDE se relacione directamente con un estilo particular de comentar código. Por supuesto, estamos hablando de C# y la documentación XML.

Aunque para nada son obsoletos los // y /**/, los comentarios XML son usados por el IDE para describirnos, en tiempo real, las características de los métodos u objetos comentados cuando en un futuro los estemos utilizando. Recuerden, por ejemplo, como siempre que usamos un objeto X y escribimos un punto a continuación de su identificador (x.), enseguida nos muestra una lista de las opciones disponibles, como sus métodos, y de estos su tipo de retorno, descripción, parámetros, etc. Esto sucede porque dichos métodos fueron comentados con XML. En la siguiente imagen podemos llevarnos mejor la idea:

Creando comentarios XML:

Con XML podemos comentar: clases, delegados, interfaces, campos, eventos, propiedades y métodos. La manera de trabajar con todos es, antes de su definición, teclear tres ´/´ (///) y aparecerá, en dependencia del caso, una estructura en XML a completar.

Para el caso de un método string Califica(int nota){}, aparecerá:

///<summary>
///Este método califica en Excelente, Muy Bien, Bien…
///</summary>
///<param name="nota">Nota cuantitativa del estudiante</param>
/// <returns>Nota cualitativa</returns>
public string Califica(int nota)

Seguro se dan cuenta de para qué se utilizan etiquetas como summary, param y returns. Vamos a ver como nos clasifica José Antonio González Seco en su libro "El lenguaje de programación C#", muchas de ellas:

Etiquetas de uso genérico
Éstas se utilizan para cualquier objeto que tratemos de comentar:

  • <summary>: Su contenido se utiliza para indicar un resumen sobre el significado del elemento al que precede. Cuando utilizamos el operador . para acceder a algún miembro de un objeto se mostrará esta información.
  • <remarks>: Su contenido indica una explicación detallada sobre el elemento al que precede. Se recomienda usar <remarks> para dar una explicación detallada de los tipos de datos y <summary> para dar una resumida de cada uno de sus miembros.
  • <example>: Su contenido es un ejemplo sobre cómo usar el elemento al que precede.
  • <seealso>: Se usa para indicar un elemento cuya documentación guarda alguna relación con la del elemento al que precede.
  • <permission>: Se utiliza para indicar qué permiso necesita un elemento para poder funcionar.

Etiquetas relativas a métodos
Además de las etiquetas de uso general ya vistas, en las definiciones de métodos se pueden usar las siguientes:

  • <param>: Permite documentar el significado de un parámetro de un método.
  • <paramref>: Se usa para referenciar a parámetros de métodos. No tiene contenido y el nombre del parámetro referenciado se indica en su atributo name.
  • <returns>: Permite documentar el significado del valor de retorno de un método.

Etiquetas relativas a propiedades
El uso más habitual de una propiedad consiste en controlar la forma en que se accede a un campo privado, por lo que ésta se comporta como si almacenase un valor. Mediante el contenido de la etiqueta <value> es posible describir el significado de ese valor:

/// <value>Edad de la persona representada</value>
public int Edad{
  set { edad = (value<0)? 0:value }
  get { return edad; }
}

Etiquetas relativas a excepciones
Para documentar el significado de un tipo defindo como excepción, puede incluirse un resumen sobre el mismo como contenido de una etiqueta de documentación <exception> que preceda a su definición. El atributo cref de ésta suele usarse para indicar la clase de la que deriva la excepción definida. Por ejemplo:

<exception cref="System.Exception">
/// Excepción creada para cuando se reproduzca reggaeton.
/// </exception>
class MusicException: Exception
{}

Etiquetas relativas a formato
Para mejorar la forma de expresar el contenido (simple pacotilla) de las etiquetas de documentación que se utilicen, es posible incluir en ellas las siguientes etiquetas de formato:

  • <see>:Se utiliza para indicar hipervínculos a otros elementos de la documentación generada. Nos puede interesar relacionar un objetivo con otro ya comentado.
  • <code> y <c>: Ambas etiquetas se usan para delimitar textos han de ser considerarse fragmentos de código fuente.
  • <para>: Se usa para delimitar párrafos dentro del texto contenido en otras etiquetas. Como <p></p> en HTML.
  • <list>: Se utiliza para incluir listas y tablas como contenido de otras etiquetas.

Generar un archivo XML sobre la solucion comentada:

Podemos crear archivos XML que se compilen al mismo tiempo de la compilación del código. Estos archivos son difícil de entender, por lo que hay que agregarle al comienzo una línea que especifíque la hoja de estilo con que se quiere publicar.

<?xml:stylesheet href="<ficheroXSL>" type="text/xsl"?>

Si no sabemos crear hojas de estilo XSL, podemos generar reportes web con Visual Studio como veremos más adelante. Para crear un archivo XML sobre la documentación cuando se compile la solución:

VS 2003: View » Property Pages » Configuration Properties » Build » XML Documentation File. En el diálogo que aparece especificar el nombre de la documentación en XML.

VS 2005: Project » Application Properties » Build » Output » XML Docum. File. Al igual que en el caso anterior, indicar dónde quieres el archivo y con qué nombre.

Generar Reporte Web de Comentarios:

Visual Studio .NET permite generar automáticamente un reporte en formato HTML de todos los comentarios XML que fueron colocados en el proyecto o solución; si la solución tiene más de un proyecto se documentarán todas las clases con sus respectivos métodos y miembros clasificadas de acuerdo a sus respectivos proyectos.

Para utilizar esta herramienta en VS 2003 apuntamos al menú de Herramientas (Tools), y seleccionamos la opción Generar Reporte Web de Comentarios (Build Comment Web Pages), tal como se muestra en la siguiente figura:

Aparecerá un cuadro de diálogo que nos presentará dos opciones:
• Realizar los comentarios de toda la solución.
• Realizar los comentarios de los proyectos seleccionados.

La lista de proyectos se encuentra bajo estas dos opciones, donde se puede seleccionar los proyectos a los cuales se aplicará la generación de los Comentarios Web. Luego de esto podemos seleccionar la carpeta de destino del archivo de Comentarios Web, el mismo que puede ser añadido a los Favoritos de Internet Explorer para poder acceder a él directamente. Dejaremos las opciones predeterminadas.

Realizando este artículo, traté de generar un reporte en VS 2005 y no encontré la manera. Por lo menos no aparece explícitamente. Si algún lector ha resuelto este inconveniente, por favor, tire algunos strings para BlackHat con la solución.

Conclusiones:

Como pudimos ver, es posible crear la documentación de nuestro proyecto de forma automática, sólo completando las etiquetas del XML. El hecho que la misma se genera a partir de los fuentes permite hacer ambas cosas a la vez, programar y documentar. Si eso no fuera un fuerte motivo, utilizar las bondades del IntelliSense del IDE, a la hora de usar métodos, clases o variables nos compromete aún más con la idea.

Para saber más...



Artículos relacionados


No hay comentarios: