Putting it together

by Luismi Cavallé

Documentación

Un par de posts recientes de Oren Eini (aka Ayende Rahien, un tío al que merece la pena seguir si desarrollas en .NET y quieres pensar diferente) me dan pie a tratar el peliagudo asunto de la documentación en el mundo del desarrollo de software.

El título de este post (como el de Ayende) se refiere a uno de los cuatro principios del manifiesto ágil. Cabe recordar, antes de nada, que el propio manifiesto hace hincapié en que no es que no haya ningún valor en la segunda parte de cada principio (en este caso, “documentación exhaustiva”), sino que se encuentra más valor en la primera parte del mismo.

Los problemas que un enfoque de desarrollo ágil encuentra en la documentación son algunos de los siguientes: En primer lugar es una cuestión de lenguaje. Ninguna documentación será completamente precisa siempre que esté expresada total o parcialmente en lenguaje natural, que es ambiguo. En segundo lugar, la documentación tiende a desactualizarse, de hecho a menudo queda desactualizada antes de completarse. En consecuencia, el esfuerzo y el tiempo (es decir, el coste) necesarios para mantener una documentación exhaustiva actualizada son muy grandes. Además es una tarea tediosa que suele no agradar al que la realiza (este factor tampoco debería ignorarse completamente pues probablemente tenga una repercusión en la calidad de la misma). En todo caso, no existe una manera precisa y fiable (automática) de asegurarnos que la documentación es completa y está actualizada.

El único entregable preciso, actualizado e, incluso, capaz de autoverificarse del que disponemos es el código fuente. En este sentido, el desafio ágil es el siguiente: ¿sería posible escribir un código lo suficientemente claro y sencillo (lo suficientemente bonito) como para minimizar la documentación necesaria para entenderlo? Porque, si necesitamos documentación para entender el código que escribimos o escriben otros, ¿no será que el problema lo tenemos con el código, que no es tan mantenible como debería?

En este punto me gusta recordar que los lenguajes de programación no son lenguajes para las máquinas. Las máquinas no entienden Java, ni Ruby, ni SQL. Las máquinas solo entienden un reducido juego de instrucciones en el que la mayoría de nosotros no programa. El resto son lenguajes para ser usados y entendidos por humanos. Eso sí, lenguajes precisos y con la capacidad de traducirse o interpretarse en lenguajes que entienden las máquinas.

Entendiéndolo así, ¿por qué no empezamos a sacarles partido? ¿Por qué no utilizarlos de maneras más interesantes que como meros vehículos para hacer funcionar a las máquinas? ¿Por qué no utilizarlos para comunicar intenciones o especificar comportamientos mediante DSLs y APIs más expresivas?

En el fondo la propuesta quizá no sea tanto la de documentar menos, sino la de documentar de otra manera.