Documentar código en .NET

Si hay algo obligado a hacer en cualquier proyecto en el que participen más de dos desarrolladores es documentar el código fuente. A todos los programadores nos da una pereza extrema cuando llega el momento de plasmar en palabras el resultado de varias horas, días o semanas de duro trabajo.

Pero hay que acostumbrarse a repasar  el código para comentarlo todo de manera minuciosa, de manera que el próximo desarrollador que deba mantener o modificar el código sea capaz de entender perfectamente sin necesidad de depurar lo que hace el código. Creerme, nos estará eternamente agradecidos.

Otro aspecto fundamental es comentar las clases, métodos, atributos, etc, de forma que con una breve explicación se sepa que hace, que entradas tiene y que salidas podemos esperar. Esto permitirá que realmente nuestro código sea una caja negra para el resto de desarrolladores de nuestro equipo, y tengan la certeza que están utilizando el método adecuado para el resultado que desean obtener.

Con .NET no hay excusas para no hacerlo, ya que esta gestión esta casi automatizada. Los pasos a seguir son los siguientes:


1 - Documentar los miembros

Cualquier lenguaje .NET, tiene la opción de Generar documentación, a través de comentarios con 3 slash (///) dentro del código fuente. Pulsando 3 veces la tecla "/" encima de cualquier miembro (clase, método, atributo, etc) automáticamente .NET genera una miniplantilla de código donde poder especificar los datos relacionados con el miembro en cuestión.

Todos estos comentarios luego aparecen en el Intelligence de Visual Studio cuando queremos acceder al miembro comentado.

2 - Generar la documentación

Dichos comentarios son almacenados automáticamente en un archivo XML definido. Posteriormente podemos generar la documentación. La sintaxis es la siguiente:

csc tuClase.cs /doc:tuDocumentacion.xml

Esto quiere decir que toma todos los comentarios y los almacena en el archivo XML (en el caso del ejemplo seria "tuDocumentacion.xml").

Ahora bien, si trabajamos con Visual Studio, le podemos decir que al generar o compilar, cree su archivo XML automáticamente.
Esto se encuentra en Propiedades del proyecto (proyecto, no solución) -> Generar -> y luego hay que seleccionar la casilla que dice "Archivo de documentación XML:" (nota: se debe poner tanto para Debug, como para Release).

También existe un Add-On para Visual Studio 2003, 2005 y 2008 llamado GhostDoc. Este Add-On nos ayuda en crear los comentarios, tan sólo posicionandonos sobre el miembro que queremos generar su documentación y presionando el botón derecho, le decimos "Document this".

3 - Dar formato a la documentación

Una vez creada nuestra documentación, debemos darle un formato para mostrarlo.

Existen varias posibilidades:

• Tipo msdn, que es tipo Web (Ejemplo array).
• Tipo chm, que es la típica ayuda de windows

Para ello debes descargar SandCastle quién te genera documentación tipo msdn, ahora bien, si quieres generar los arhivos tipo ayuda al estilo windows, o sea los CHM, debes descargar también HTML Help Workshop.

El único problema de SandCastle es que como no posee interfaz gráfica y el proceso es un tanto largo, la creación de la documentación se hace un tanto complicada...pero tranquilo, existe(n) una(varias) IDE(s) que abstraen la complejidad. Una de ellas se llama SandCastleGUI. (probada y de verdad es muy fácil).

No sé en el resto de lenguajes como será el tema de comentar código. ¿Es igual de fácil?