Un código autodocumentado
Richard Hillesley examina la documentación insuficiente del software libre y se pregunta si hay una mejor manera de generarla.
La poca o ausencia de documentación de software es un tema recurrente. Un debate que no falta en el ámbito de la programación. De hecho, mi compañero Miguel Catalan escribió un post sobre ello: Comentar o no comentar el código, esa es la cuestión.
Este problema se aplica con la misma frecuencia en el software propietario como en el software libre. La documentación del código tiene dos propósitos principales:
Hacer que el código sea legible por otros programadores
Hacer que el código sea utilizable
Una buena documentación de software libre es vital para los usuarios, y contribuir a la documentación (o la traducción a una lengua minoritaria) de un proyecto de software libre es una buena manera de involucrarse con la filosofía y con aquellos que no saben por dónde empezar, o cómo programar, y quieren saber cómo se hace. El problema es la escasez de reclutas.
Un código es bueno cuando está autodocumentado y se ve bien, incluso cuando no sabes cuál es su propósito. Un buen código no lo funciona, sino que incluso cuando se produce un error, es fácil de solucionar. Si dudas de tu código a simple vista es probable que sea mejor que lo reescribas desde cero, o que nunca llegues al final de problema. Un código que no contenga algún nivel de documentación interna es difícil de seguir y de mantener. Hasta Linus Torvalds pone sus pautas de estilo de programación para el kernel de Linux:
“Sabes que eres brillante, pero tal vez te gustaría entender lo que hiciste hace dos semanas”.
También sugiere que el lector de sus directrices empezará con la"impresión de una copia de los estándares de GNU, y que no terminará leyendo”. Quemarla, es un gran gesto simbólico. Torvalds es escéptico de las normas y directrices, pero su propio documento sobre el estilo de codificación es una aceptación tácita del hecho de que con un poco de documentación las cosas se hacen más fáciles. Nos gusta el código fuente, pero leerlo no es siempre la mejor manera de descubrir las intenciones del codificador —al igual que las intenciones del codificador no siempre son las mismas que lo que el código hace en realidad.
Para escribir código hay que tener estilo y aunque el buen código no tiene por qué resolver un problema de inmediato, deja la solución en su lugar para la siguiente secuencia de problemas que puedan surgir. En el sentido más amplio, la documentación y la usabilidad son conceptos intercambiables. Un programa sin una descripción clara de su propósito y parámetros es incompleto. Una buena documentación es más vital a “nivel de usuario”, y no siempre es fiable, sea cual sea su origen.
La persona que mejor conoce el código es el programador. Esto ya argumenta la necesidad de expresar el estilo y las reglas de sintaxis (flexibles) de cada uno. Si se hace bien, puede usarse un software que analice los comentarios para generar una documentación en un formato estándar. No es una idea original (Javadoc, Doxygen...) y aunque los resultados inmediatos pueden ser imperfectos, la práctica pueden mejorarlos. Ya se ha hecho antes y solo funciona si un proyecto tiene un buen conjunto de normas relativas a la documentación interna pueden mejorar el resultado, y se ha hecho antes, pero sólo puede funcionar si un proyecto tiene un buen conjunto de normas relativas a la documentación interna y la aceptación de un código.
CONCLUSIÓN
Ya sé que es pesado documentar el código. El artículo de Hillesley deja claro que es importante. Él destaca la necesidad de una autodocumentación, de hacer más fácil la generación de un documento estándar. Y para que funcione hay que ser buenos escritores, recordad que el principio fundamental de cualquier lenguaje es la comunicación. ¿Cómo podríamos entender esos tostones de ensayos sin las notas de pie de página? No me quiero imaginar miles de líneas de código a lo James Joyce.
Fuente: linux user