Documentar el código es más que dejarlo bonito. Es hacerlo entendible.

«Comentar el código es como limpiar el cuarto de baño; nadie quiere hacerlo, pero el resultado es siempre una experiencia más agradable para uno mismo y sus invitados»
— Ryan Campbell

Uno de los propósitos iniciales de este blog, era combatir mi inquietante amnesia. No se ustedes, pero me es muy frecuente, que después de muchos días, semanas o meses sin ver el código que estaba trabajando, termino olvidando que hacía o como funcionaba.

«Ley de Alzheimer de la programación: si lees un código que escribiste hace más de dos semanas es como si lo vieras por primera vez»
— Via Dan Hurvitz

Hay solo una forma de combatirlo: documentando.

Será una lata, pero creo (seriamente) que los lenguajes de programación debieran mandar advertencias cuando no documentamos el código fuente.

Cuando estuve en inserto en el proyecto GDT, me topé de cerca con Doxygen, una excelente herramienta para documentar el código en función de etiquetas especiales insertas en los comentarios. Muchos años antes, me tocó conocer otra grandiosa herramienta, que ayer re-descubrí: phpdocumentor.

¿Que tiene de fantástico?

Tiene varios detalles que lo hacen un amor:

• Esta escrito en PHP.
• En su documentación incluye los tags especiales, con ejemplos, para escribir correctamente los comentarios.
• Funciona por interfaz web y por consola. Posibilitando automatizar el proceso de documentación
• Se puede configurar, guardando un archivo personalizado .ini con las opciones. Esto permite automatizar más aún el proceso.
• Exporta a varios formatos, incluyendo HTML, PDF y CHM. Incluso tiene diversas plantillas para producir distintos estilos de HTML. También se pueden personalizar estas plantillas.

Sin duda debe tener más gracias, pero con eso es suficiente por ahora.

Ejemplos

Para probar, documenté TODAS las clases de Gonium y dejé copia acá. Sin ir más lejos, la documentación del API de Zend Framework está producida con phpDocumentor.

Sugerencia

Ser buen programador, no solo significa adoptar las mejores convenciones para escribir el código, usar el mejor IDE (esto es una estupidez, pero lo he escuchado), presumir el uso de patrones de diseño novedosos o presumir de código limpio y óptimo. Documentar es una tarea básica que DEBIERA SER OBLIGATORIA. No solo si sufres algún problema de memoria (con la de tu cabeza, no con la del PC) como yo.

Además es mucho más tedioso documentar un montón de clases ya escritas, que no sabes exactamente que hace, que comenzar documentando desde le principio. Si estas comenzando un proyecto, HAZLO YA, sino TAMBIÉN.

Caso personal

En Gonium hay algunas cuantas clases, que en su momento me pareció bueno crear mientras se me ocurría como implementarlas (por ahí por febrero de este año). Ahora no recuerdo que diablos quería hacer con ellas :B

Fuente de las citas: Variable not found: Otras 101 citas célebres del mundo de la informática.