¿Por qué Documentar el Código?

Mucho se discute sobre la documentación en el desarrollo de software: que si se debe de seguir por cumplir con la metodología al pie de la letra, que si es una buena práctica, que si se debe de realizar solo en algunos casos; y hasta en algunos casos los detractores de esta práctica opinan que solo es pérdida de tiempo.

Considero que la documentación es muy útil y necesaria. Para reforzar esta postura, analicemos los siguientes hechos:

Cada cabeza es un mundo. Al ser individuos, todos los desarrolladores piensan diferente, por lo tanto un pequeño módulo de consultas puede desarrollarse de miles de formas distintas. Incluso se puede contraponer la lógica llegando al mismo resultado. Es por eso que comúnmente los programadores dicen: ”es más fácil que lo programe nuevamente a que lo modifique”.

Según el sapo es la pedrada. Algunas personas tienen la errónea idea de que un módulo de consulta en una aplicación de escritorio se hace igual que en una aplicación web, o que un servicio web en la nube o incluso que en un dispositivo móvil. Sin embargo cada desarrollo está hecho con cierto propósito y con esos ojos debe analizarse, de otro modo se pueden asumir alcances y funciones que no se desempeñarán.

Los cambios tienen impacto. Es común escuchar algo como: “es lo mismo, solo ponle estos campos más”. No hay nada más estresante para un desarrollador de software que hacerle entender a alguien que sus “pequeños cambios” son más complejos de lo que a él le parece, que no entiende la magnitud de lo que pide y que el sistema no se diseñó para lo que se le ocurrió y/o necesita ahora.

Las personas no son eternas. Los seres humanos, incluidos los desarrolladores de software, no somos eternos. Sin llegar a hechos trágicos, es muy común la rotación de personal. Cada vez es más común la inclusión de freelancers en proyectos y éstos no están siempre disponibles para los cambios y mejoras; lo que da como resultado invertir mucho mayor tiempo en investigar, analizar y hacer ingeniería inversa, y ni mencionar el asegurarse que no se afecten otras secciones del desarrollo.

El tiempo es la mejor forma de olvidar. ¿Alguien se acuerda de esa clase que hiciste tan increíble y perfecta que sabes que funciona de maravilla y que jamás has necesitado darle mantenimiento en los últimos tres años? Solo algunos privilegiados poseen memoria eidética y aun así es improbable recordar la lógica que se aplicó para hacer algo hace muchos años.

Un ejemplo

Imaginemos el siguiente escenario: se compra una casa que alguien construyó hace algunos años y se necesita conectar un lavabo a la línea principal del desagüe y no se tienen los planos de la casa. ¿Qué se tendría que hacer?, pues romper paredes y excavar hoyos hasta encontrar la línea principal del desagüe y a partir de ahí ver cuál sería la forma más simple de conectar el lavabo. ¿Qué pasaría si se decidiera poner una ventana?, se podría romper un cable y generar un corto, o romper una tubería de agua o un ducto de gas o simplemente afectar la integridad estructural de la casa. Cualquiera de estos posibles resultados genera un problema mayor a la mejora que se planeaba hacer en un principio. Como se puede apreciar, un pequeño cambio puede tener afectaciones demasiado grandes que no se pueden apreciar a simple vista.

De lo anterior se podría asumir desde un punto de vista lógico que una buena documentación ofrece:

• Garantías de un producto final de la mayor calidad.
• Seguridad en el cumplimiento de los tiempos y costos del proyecto.
• La confianza de que se determina el mejor proceso para desarrollar su producto.
• Que el producto contará con la escalabilidad necesaria para seguir creciendo.

Desgraciadamente algunos clientes no aprecian todas las bondades que ofrece un desarrollo de software con una correcta documentación. Por el contrario, cuando un desarrollador comete el error de mencionar que se cobra la documentación, se suele malinterpretar como un abuso, provocando este tipo de reacciones: ¿para qué necesitas documentar si yo te puedo decir todo?

Recordemos que el desarrollo de software es una disciplina nueva y la gran mayoría de los desarrollos se realizan de forma artesanal, como algún misterio que solo pocos entienden y muchos menos pueden explicar. Documentar es la solución del misterio. A través de la documentación se logra que muchos entiendan lo que alguien desarrolló años atrás; y es solo una cuestión de tiempo, disciplina y educación al cliente para que se vea con buenos ojos cobrar por una correcta documentación, tal como hoy un arquitecto cobra por los planos de una casa.