Documentando en C#

La documentación del código es una tarea laboriosa, pero que conviene simultanear con la escritura del mismo para evitar posibles omisiones y errores a la hora de llevarla a cabo. Un código bien organizado y estructurado no necesitará, a priori, comentarios dentro del cuerpo de las funciones, procedimientos o métodos (salvo algún //TODO que convendrá repasar, y alguna que otra aclaración), pero sí es interesante (más que eso, imprescindible) comentar las cabeceras de los métodos y clases (sí, en C# que es el lenguaje elegido para esta entrada, con la triple barra: ///), para facilitar su uso, por un lado, permitiendo al Intellisense incluir los comentarios en un tooltip cuando estamos usando las clases, así como para generar una documentación clara y precisa con las herramientas adecuadas (Sandcastle, por ejemplo).

 

Con la intención de hacer más llevadera la tarea, Roland Weigelt proporciona un add-in gratuito para todas las versiones de Visual Studio para el .NET Framework (a saber, de momento VS 2003, 2005 y 2008). GhostDoc, el add-in, estará listo para ser usado simplemente con instalarlo y volver a iniciar Visual Studio. Ahora, simplemente debemos escribir el código y, pulsando con el botón derecho del ratón (o usando el atajo de teclado que hayamos configurado en las opciones del add-in) seleccionaremos la opción Document this, y él se encargará de crear la estructura del comentario. Aunque parezca un poco absurdo (ya que Visual Studio crea dicha estructura al escribir la triple barra sobre un nombre de clase o método, lo cierto es que GhostDoc llega un poco más allá, ya que recupera la documentación de las clases bases que podamos heredar, y deduce parte de la información de los métodos a partir de los parámetros que incluyan, por lo que reduce (aunque sea una pizca) el trabajo a realizar. Como afirma el propio autor,

GhostDoc is a free add-in for Visual Studio that automatically generates XML documentation comments for C#. Either by using existing documentation inherited from base classes or implemented interfaces, or by deducing comments from
name and type of e.g. methods, properties or parameters.