July 2010 - Artículos - Jorge Serrano - MVP Visual Developer - Visual Basic

July 2010 - Artículos

Siempre que programamos nos deberíamos encontrar con la necesidad de documentar nuestros proyectos de manera que tengamos una documentación asociada al proyecto y lo más cerca de nuestras manos.

Separando los análisis de requerimientos o los diseños técnicos a un lado por poner dos tipos de documentos esenciales en todo proyecto, la documentación más frecuente para un programador son los ficheros de ayuda.
No me refiero a los ficheros de ayuda de usuario, sino a los ficheros de ayuda de desarrollo y programación.

Evidentemente (y no debemos olvidarlo nunca), hay siempre un coste asociado al tiempo dedicado por un programador a la codificación y que no está estrechamente ligado con las instrucciones de código, son los comentarios de código.
En muchas empresas no se entiende esta labor de documentación como una inversión que aporte beneficio para el desarrollo empresarial, sino como un gasto.
A la larga, muchas de esas empresas terminan gastando más dinero en tratar de entender cómo funcionaba una parte del código que en ir directamente a un fichero de ayuda, leerlo y comprenderlo de forma efectiva y rápida.
Pero no sólo con un fichero de ayuda nos basta, también tenemos que tener claro que el fichero de ayuda debe estar bien cumplimentado, y eso se hace desde el código y en el caso de .NET con los comentarios XML.

Sin embargo, para generarlos debemos tener claras varias pautas.

Por un lado que documentar el código es una tarea MUY importante. Escribir comentarios como "Esto es una clase" no nos aporta ningún valor adicional. A veces las prisas nos lleva a escribir este tipo de comentarios, pero casi mejor no poner nada a poner algo que no nos aporta valor.
Lo ideal y recomendado es comentar al mismo tiempo que se programa. De esa manera nunca dejaremos nada en el cajón del recuerdo y haremos las cosas a un mismo ritmo y con la idea fresca de lo que se escribe.
Sé que hay gente que opina que si el código está lo suficientemente bien hecho no es necesario escribir apenas comentarios, sin embargo (y es una opinión muy personal), no estoy nada de acuerdo con esta afirmación. Los proyectos cambian, avanzan, y las personas que trabajan con un proyecto también, por lo que los comentarios son más que recomendables,... casi diria obligados.
De los anteriores puntos se desprende que los comentarios deben obviamente aportarnos valor. En caso contrario, los comentarios de código no sirven de nada.

Es obvio no obstante, que al iniciar un proyecto debemos preparar una documentación de estilos de documentación que se utilice a lo largo de todas y cada una de las fases y de las clases que forman parte del proyecto.
Cabeceras, comentarios tipo, referencias, ejemplos, etc.

También sé que los comentarios no se compilan, y que por lo tanto, no dan un valor añadido directo al ensamblado, módulo o codificación en cuestión, sin embargo, sí otorga un papel relevante y un beneficio indirecto que es muy importante tener en consideración y que es el que muchos obvian.

En Internet podemos encontrar mucha documentación sobre como escribir nuestros comentarios Xml en .NET.
Sirva como material de apoyo el siguiente documento Word.

Y llegados a este punto, ¿qué Software tenemos para ayudarnos a documentar nuestros proyectos?.

A mí me encanta uno de ellos llamado Document! X de Innovasis.
Sin embargo, tendremos que tener en cuenta su coste que asciende a 357€ para 1 usuario.

Si no nos queremos rascar el bolsillo, entonces podremos irnos a una solución gratuita, con muchas menos cosas que las que nos ofrece Document! X, pero que nos puede sacar del lío.
Me refiero a Sandcastle.

Sandcastle era un proyecto que nos ayudaba a documentar nuestros ensamblados, sin embargo, el proyecto parecía haberse quedado muerto hasta el pasado mes de Junio, en el que la gente de Sandcastle actualizó su producto.

Sin embargo, la instalación real requiere tres acciones que paso a enumerar una a una:

1) La primera de todas es que debemos descargarnos el HTML Help Workshop and Documentation de Microsoft.
Allí encontraremos un fichero de nombre htmlhelp.exe y de 3.3 Mb.
Descargaremos el fichero y lo instalaremos en la máquina cliente.

2) La segunda acción es instalar Sandcastle - Documentation Compiler for Managed Class Libraries.
El proyecto está en Codeplex y su última versión es del pasado 23 de Junio de 2010 (v2.6.1062.1).
Descargaremos el fichero sandcastle.msi de casi 15 Mb y lo instalaremos en la máquina cliente.

3) La tercera acción es instalar Sandcastle Help File Builder.
Este proyecto está también en CodePlex y los permite trabajar con una interfaz gráfica realmente cómoda para indicar qué ensamblados queremos documentar en fichero de ayuda, así como las referencias de los ensamblados y otras características.
La versión última es la v1.9.1.0 de fecha 7 de Julio de 2010.
El fichero Sandcastle Help File Builder Installer de casi 9 Mb nos permitirá instalar la interfaz de usuario que trabaja con Sandcastle Documentarion Compiler for Managed Class Libraries comentado en el punto 2.

Una vez concluida la instalación de estos paquetes, te recomiendo reiniciar el equipo para evitar sorpresas.

Con estas acciones, podremos preparar con Sandcastle Help File Builder un proyecto de compilación de ayuda, indicar los ensamblados que queremos documentar y ejecutar el compilador de ayudas.
El proceso tarda un rato, pero nos generará un log de mensajes de error, warning e información, además de compilar el fichero de ayuda.
Allí podremos repasar igualmente si faltan comentarios en los ficheros de ayuda, si hay comentarios mal escritos, etc.