Sin documentos no hay hockey

En su libro “Advanced PHP programming”, George Schlossnagle hace la siguiente afirmación:

En mi empresa, el código producido para los clientes no se considera completo hasta que toda su interfaz externa de programación de la aplicación (API) y cualquier idiosincrasia interna están totalmente documentadas.

Esta declaración de Schlossnagle es una buena señal de lo importante que puede llegar a ser la gestión de la documentación del código fuente dentro de un proyecto de desarrollo de software.

Antes de proseguir, habría que discernir entre la documentación del proyecto y la documentación del código.

La primera puede contener requerimientos, casos de uso, diagramas y otros tipos de documentos cuya finalidad es definir el producto que se desea obtener y el modo de hacerlo. Sin embargo, la documentación del código, que es la que se trata en este breve texto, forma parte del producto final como se puede deducir de la frase de Schlossnagle.

Además, este mismo autor divide la documentación del código en dos tipos: Los comentarios que los desarrolladores escriben junto a sus líneas de código explicando cómo funciona y los documentos donde se detalla que es lo que hace nuestro código. Haciendo un símil con la documentación de un aparato electrónico, el primer tipo descrito representaría el manual de reparaciones para los empleados del soporte técnico o datasheet, y el segundo tipo coincidiría con las instrucciones de uso para el usuario.

Un ingeniero en Electrónica, con toda seguridad, es capaz de desarticular un aparato electrónico y, descifrando el modo en el que se ha diseñado que sus componentes interactúen, entender cómo consigue realizar la función para la que dicho aparato fué fabricado. A esta acción de deducir como fue fabricado un producto y qué lo hace funcionar se le llama ingeniería inversa, y es un proceso difícil y muy laborioso. Nuestro ingeniero también sería capaz de realizar modificaciones en el artilugio para mejorarlo o personalizarlo según nuestras necesidades, pero si le facilitamos un datasheet, una documentación técnica, el tiempo que necesitará para hacerlo disminuiría obstensiblemente.

Si en nuestros desarrollos de software nos aseguramos de que todo el equipo gestiona el primer tipo de documentación de código que mencionábamos, a saber, la documentación técnica sobre cómo funciona, vamos a obtener beneficios de rendimiento, pues las revisiones de código y la depuración de errores se realizarán de un modo ágil. Estos comentarios dentro del mismo código son equiparables al mencionado datasheet de un producto electrónico, y nos ayudarán a recordar rápidamente el modo en el que habíamos ideado un código antiguo si necesitamos ojearlo más tarde para hacer mejoras en él. Definitivamente, facilita la compresión del código sin necesidad de hacer una durísima ingeniería inversa, independientemente de que el código fuera escrito por nosotros o por otro desarrollador.

Para ejecutar un desarrollo de sofware de calidad, especialmente cuando lo queremos dotar de una API externa, también es indispensable una documentación donde se pueda acceder a la información sobre qué trabajo realiza cada elemento, y sobre qué es lo que necesita para realizarlo; es decir, necesitamos poder comprender el uso y el funcionamiento de los componentes programados sin necesidad de ojear su código fuente. Gestionar la documentación API, el manual de instrucciones de uso, es también una ayuda en el momento del desarrollo: en ocasiones, documentando clases de código recién escritas, he descubierto que la lógica usada no era buena, y he podido rehacer mi trabajo a tiempo para mejorarlo. El hecho de que una tecnología como Java incorpore el sistema de documentación automática JavaDoc, y que dicho sistema haya sido imitado para otros lenguajes de programación, nos muestra la importancia de esta documentación tanto para el desarrollo como para el uso de nuestro producto final.

Imaginemos ahora que adquirimos un robot aspirador automático, uno de esos aparatos que pasean solos por nuestra casa recogiendo la suciedad del suelo mientras nosotros nos podemos dedicar a cualquier otra tarea. Seguro que el pequeño barrendero electrónico dispone de una gran cantidad de parámetros para poder configurar la tarea de limpieza: programar la hora de inicio, la intensidad, la eficiencia, la hora de apagado, etcétera. ¿Cuál sería tu impresión si, al sacarlo de su caja nuevecito y listo para estrenar, no pudieras localizar en el aparato ningún botón o interruptor y comprobaras, además, que no dispone de manual de instrucciones? Recibir un producto software con una API externa sin documentar es algo muy parecido a que te regalen un enorme puck de hockey con la promesa de que limpiará tu hogar.