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?

Basta de 'copy&paste' en nuestros desarrollos

Alguna vez, alguien debería decirle a cualquier desarrollador de cualquier proyecto que cada vez que copia y pega código, Dios mata a un gatito.

Y es que el antipatrón programación corta y pega es un mal que aparece a menudo en muchos proyectos. Los problemas que se derivan de este antipatrón son muy numerosos, sobre todo relacionados con la mantenibilidad del código. Cuantas veces se propaga codigo que tiene algún error no detectado, y cuando se hace, es imposible subsanarlo en aquellos sitios donde se ha utilizado el copia-pega.

Básicamente, la programación copy&paste se trata de una violación en toda regla un principio básico en el desarrollo de software, el principio DRY (Don't repeat yourself). Las duplicidades en el código a menudo llevan a inconsistencias y son un indicador claro de que el código no se está refactorizando adecuadamente.

Si bien es cierto que todo desarrollador experimentado sabe que a la larga el copy-paste es dañino, también es cierto que es algo que todos hemos hecho en alguna ocasión y que muchos desarrolladores poco experimentados a menudo abusan del copy-paste. El problema viene de que cuando este abuso se detecta el mal ya esta hecho. Basta un desarrollador poco displicinado o poco experimentado que caiga en este error para que el proyecto sufra los problemas derivados del mismo.

Conscientes de este problema ha nacido Clone Detective for Visual Studio, un addon perfectamente integrado en Visual Studio cuyo cometido es detectar donde se están introduciendo duplicidades en el código, bien por copy-paste o bien por errores de diseño que obligan a introducir código muy similar. De momento solo funciona para C#.

Si queréis ver como funciona antes de instalarlo visitad la sección de videos de la web del proyecto en Codeplex. Una herramienta muy util.



Gracias al articulo de Rodrigo Corral por descubrirme la herramienta

Reviviendo el blog

Hacía tiempo que quería volver a darle utilidad al antiguo blog, que se había quedado desfasado y sin la calidad de temas que buscaba.

A lo largo de este tiempo, esto de llevar un lustro trabajando ya se empieza a notar, he ido recopilando soluciones, cursiodades, problemas que creo que pueden ser de utilidad compartirlos con los demás. Y es que ya va siendo hora de devolver a la comunidad algo de utilidad (que no se ya cuantas veces al día entro a google para preguntarle sobre el error o problema que tengo en la pantalla).

Desde la perspectiva de desarrollador y jefe de proyectos, espero poder ofrecer temas que os sean de interés.

Saludos, espero que sigáis este blog con frecuencia