Cualquiera que haya programado un poco y que haya usado el mismo código en más de un sitio, sabe la importancia de documentar el código. Hay días que uno esta realmente esta inspirado y la siguiente vez que miras el código piensas: "uh-oh, esto lo programé yo? Que demonios había bebido?" Entonces te das cuenta que, si no has incluido comentarios, te cuesta entender hasta tu propio código.
Se puede dividir los comentarios en dos grupos: los que documentan el codigo para entender parte por parte como funciona un metodo y como aquellos que documentan la funcion, para que sirve cada parámetro, de devuelve, etc. Lo primero es largo de explicar y cada uno tiene su sistema. Para lo segundo existen algunos sistemas de documentacion automatica que, a partir de los comentarios debidamente formateados producen documentación en forma de pagina web.
El sistema de generación de documentación más usado para C++ es sin duda el Doxygen. Facil de usar, sin duda, el resultado es detallado y flexible. El resultado se puede subir directamente a un servidor como sitio web. Es perfecto? Bueno, una vez tienes todas tus funciones documentadas, lo es.
Y ahí vamos al quid de la cuestión. Uno de los problemas que siempre tengo cuando me dedico a documentar es que me aburre formatear los comentarios para que se los trague Doxygen, por que Visual C++ no tiene un sistema de comentarios flexible. Si tiene todo un sistema para C# pero creo que Doxygen de momento no lo paresa. Hace un par de días pude probar este plugin para VC++ 2008. Se llama Atomineer Utils, y la verdad es que me ha gustado mucho. Para empezar es gratis (la palabra mágica). Se integra en el menu de herramientas de VC++ una vez instalado. Si lo instalas por defecto, no necesita configuración extra así que en ese sentido es muy cómodo.
Luego vemos que en Herramientas ha aparecido una nueva opcion. Lo podemos configurar para que los comentarios tengan la pinta que queramos. Es decir, que dentro de los formatos permitidos por Doxygen podemos elegir el que nos guste para que sean agradables para nosotros.
Una vez configurado al gusto solo tenemos que ir a la función, poner el cursor encima de la clase, del metodo o propiedad que queramos documentar, vamos a Herramientas-->Atomineer Utils--> Add Doc Comment,
y nos aparecerán los comentarios necesarios y preparados para que los rellenemos.
Y esas solo son algunas de las opciones. Como decia antes, ya no quedan excusas para documentar nuestro código.
No hay comentarios:
Publicar un comentario