Documentando el codigo
Febrero 11th, 2006Uno de los errores mas graves que tengo cuando programo es que no me gusta comentar el codigo que hago. Y claro, es que pienso que gasto tiempo valioso: el tiempo que ocupo en escribir dos lineas de comentario, podria utilizarlo en crear un par de funciones, o una clase entera. Pues estoy muy equivocado. Esos pocos segundos que me ahorro por no documentar, me cuestan caro despues, cuando necesito actualizar mi codigo y no recuerdo lo que hice, que variables use, por que cree tal o cual funcion. De igual manera pasa cuando quiero reutilizar el codigo, pero no recuerdo como usarlo.
Pues bien, por eso es importantisimo documentar el codigo. Ademas, hay herramientas (para cada lenguaje de programacion) que me ayudan a crear una documentacion bonita y organizada a partir de los comentarios que he puesto en mi codigo. Hacer esto ayuda mucho, no solo para organizarte, sino tambien si deseas distribuir tu codigo: una documentacion bien realizada, facilita el uso del codigo.
En el caso de actionscript, hay varios programas, algunos estan listados en osflash. Me decidi probar dos: NaturalDocs y as2api. Cada uno tiene reglas especificas para documentar tu codigo, para luego correr un comando que parsea estos comentarios y genera la documentacion.
Me gusta NaturalDocs por el hecho de que sus reglas son mucho mas faciles de recordar. La presentacion de la documentacion es bastante elegante, y sobretodo es facil de usar. Tambien puedes configurar y crear nuevos menus a tu gusto (cambiando los archivos de documentacion). Ademas, esta herramienta no es solamente para actionscript, puedes usarla para generar documentacion de distintos lenguajes de programacion como php, java, coldfusion, python, javascript, entre otros (ver la lista de lenguajes soportados). Luego de probarlo, hay solamente dos cosas que no me gustaron: documenta tambien funciones y variables privadas (que generalmente deseas ocultarlas) y si tienes funciones getter y setter, las documenta como dos metodos distintos.
as2api es un programa solamente para actionscript. Su sintaxis y estilo de documentacion estan basados en javadoc (herramienta para java). A pesar de que apenas esta en su version 0.4, as2api es bastante completo. Sus reglas de documentacion son faciles de aprender, sobretodo si has utilizado javadoc anteriormente. Que es lo que no me gusta de esta herramienta? que la documentacion generada se ve horrible 
pero todo es cuestion de jugar un poco con su hoja de estilos. La herramienta es mas basica, pero eso no significa que no sea buena.
Para muestra un boton: estoy trabajando en un proyecto del que hablare despues y que sera libre para que lo bajen. Probe ambas herramientas, y estos son los resultados:
Naturaldocs: mi documentacion (esta incompleta, pues no use sus reglas para comentar mi codigo)
As2api: mi documentacion sin modificar.
As2api: mi documentacion, despues de modificar la hoja de estilos.
En fin, me quede con as2api (con mi hoja de estilos). No es lo mejor del mundo, pero basta y sobra para mantener una buena documentacion de mi codigo.
Si programas en php, te recomiendo phpdoc
Finalmente, se que no el blog no ha estado muy activo, pero proximamente estare posteando un poco mas, sobre como utilizar as2api, utilizar clases abstractas, flickr, mi proyecto (del que acaban de ver la documentacion), entre otras cosas.