Efectivamente, no nos gusta documentar. Esta afirmación llevo muchos años oyéndola, diciéndola y sufriéndola.
¿Porqué no nos gusta documentar?
Pues porque no nos proporciona ningún beneficio aparente. ¿Me cambia en algo la vida si documento 1, 2 o 700 páginas? Probablemente no.
Pero claro, esto es porque lo afirmamos mientras documentamos. Documentar no da el mismo tipo de satisfacción a los programadores que tirar líneas de código. ¿Qué pasa si dejamos pasar los años y tratamos de mantener un sistema sin documentación? Pueden pasar dos cosas:
Ahí está la clave: no se comenta el código para tener documentación, sino para acelerar los cambios en el código siempre que el objetivo del mismo ni sus circunstancias cambien. Si las circunstancias, la interrelación entre componentes, los requisitos, etc cambian...de poco me sirve el código ni sus comentarios.
Me hace mucha gracia quien afirma que la mejor documentación es el código. Me preocupa y me hace dudar de si esa persona ha mantenido proyectos grandes y antiguos. Las realidades de la empresa cambian, los programas y módulos con los que interactuamos cambian...los sistemas físicos en la empresa cambian. Tener que tirar del hilo del código y sus comentarios para tratar de deducir decisiones antiguas es agotador...e inútil. Porque es el pasado.
Hay quien afirma y afirmará que el código documentado lo es todo gracias a las habituales "balas de plata": patrones de diseño y arquitectura, buenas prácticas, estándares de desarrollo...Eso está muy bien para pequeños cambios y proyectos no muy antiguos. Pero la realidad es que todo eso ha cambiado en el tiempo. Lo que hoy nos parece la piedra filosofal, mañana estará obsoleto y habrá otros patrones, estándares, etc. Mantener código antiguo nos suele llevar a criticar a su autor, simplemente porque no entendemos las "balas de plata" de aquel momento (bueno, de acuerdo, a veces también hay código antiguo realmente horrendo).
Otro problema está en la dispersión y el tamaño. Está muy bien mantener código con comentarios de módulos pequeños, o sistemas concentrados. ¿Qué ocurre si mi código tiene millones de líneas de código, miles de módulos distribuidos en docenas de aplicaciones? ¿Qué ocurre si no tengo siquiera visibilidad de parte del código o de las aplicaciones porque son de otras empresas?
Aquí de nuevo entran en juego la documentación y los estándares. El primer punto a documentar es siempre las APIs o interfaces. Tanto si son nuestras como si no. Un fallo en el código no sabremos si es porque está mal implantada una API, si está con una versión obsoleta...a no ser que tengamos la documentación actualizada de esa API o interfaz. Los comentarios y la documentación, han de satisfacer objetivos diferentes.
Otra razón ineludible de documentar es la esencia misma de la orientación a objetos: abstracción, encapsulación, etc. Una capa de la arquitectura no puede saber de otra. Lo mismo las funciones o módulos. ¿Entonces cómo rastreo las decisiones que abarcan varios elementos si están dispersos y no saben unos de otros? ¿O es que tengo que hacer un "meta-comentario" (comentario de comentarios)? En realidad, esto que acabo de decir, no es ni más ni menos que la documentación que queremos evitar.
La mejor documentación, es la que está orientada a complementar al código y sus comentarios. Habitualmente, se hace a través de los entregables típicos:
¿Estoy diciendo que estos entregables deben hacerse? No, para nada.
¿Tienen que ser 3? Pues tampoco. El hacer 1, 2 o 3 documentos dependerá del contexto. Incluso un breve correo puede ser un análisis funcional de un pequeño cambio. Y no necesitas más. Dependerá de la metodología que se haya definido para el proyecto, el tamaño del mismo, la experiencia...
Lo que digo es que los anteriores son entregables típicos y satisfacen una necesidad. Pero una metodología que obliga de forma rígida (las que por desgracia se implantan en muchísimas empresas), son la causa de las críticas que hay hacia la documentación y hacia las propias metodologías. Si la metodología no se adapta a la realidad del proyecto, será un obstáculo, no un acelerador del trabajo.
¿Cuál es el límite? ¿Hasta dónde documentar? Eso, por desgracia, lo da la experiencia. Yo suelo dar en mis formaciones una máxima: si el analista técnico tiene dudas, es que el funcional necesita más. Si el programador no sabe qué hacer, seguramente el diseño técnico cojea.
Ojo: tampoco quiero decir que no contestemos a la persona que ha de continuar el trabajo. Yo por ejemplo, en un cliente, revisaba la documentación técnica con los programadores, y o bien modificaba el diseño técnico sobre la marcha, o directamente les indicaba cómo quería realizar las cosas, y ellos por un lado, y yo por el otro, seguíamos cada uno haciendo código/documentos. De hecho, algunos programadores terminaban llevando a cabo una solución ligeramente distinta: ellos después me explicaban el motivo, y yo adaptaba el documento a su realidad. Cuesta tiempo llegar a este nivel de colaboración, pero es un placer trabajar así. Das libertad a quien está a pie de teclado soltando código, y al final, lo importante, es que la documentación y el código no se descuadren, y que el equipo sienta que hay cierta libertad de hacer las cosas.
Y un apunte final: todo lo dicho aquí, sirve para cualquier ciclo de vida: cascada, iterativo, RUP, scrum, etc, etc. Siempre alguien tendrá que empezar a trabajar partiendo de algo que le habrán dado: un documento, una servilleta, un post-it en una pizarra...
 |
| La documentación debe estar al servicio del proyecto y no al revés |
¿Porqué no nos gusta documentar?
Pues porque no nos proporciona ningún beneficio aparente. ¿Me cambia en algo la vida si documento 1, 2 o 700 páginas? Probablemente no.
Pero claro, esto es porque lo afirmamos mientras documentamos. Documentar no da el mismo tipo de satisfacción a los programadores que tirar líneas de código. ¿Qué pasa si dejamos pasar los años y tratamos de mantener un sistema sin documentación? Pueden pasar dos cosas:
- Yo mismo soy el autor del código, y dependeré de mi memoria. Esto apenas me ha pasado el 10% de las veces (el mantener mi propio código pasado mucho tiempo). Y mi memoria, sobre lo cual me considero una persona normalita, no es capaz de retener todas las decisiones funcionales y técnicas que dan lugar a cientos, miles de líneas de código en cada proyecto.
- El autor del código no está. Bajo mi experiencia, esto me ha pasado alrededor del 90% de las veces. Bien porque he cambiado de empresa y tengo que lidiar con las perlas de otros, o bien porque la persona que lo hizo o empezó ya no está, y ahora yo tengo que mantener lo suyo. En este caso, dependeré de lo bien que el autor o autores lo hayan comentado. Pero como veremos a continuación, tampoco será de utilidad.
Ahí está la clave: no se comenta el código para tener documentación, sino para acelerar los cambios en el código siempre que el objetivo del mismo ni sus circunstancias cambien. Si las circunstancias, la interrelación entre componentes, los requisitos, etc cambian...de poco me sirve el código ni sus comentarios.
Me hace mucha gracia quien afirma que la mejor documentación es el código. Me preocupa y me hace dudar de si esa persona ha mantenido proyectos grandes y antiguos. Las realidades de la empresa cambian, los programas y módulos con los que interactuamos cambian...los sistemas físicos en la empresa cambian. Tener que tirar del hilo del código y sus comentarios para tratar de deducir decisiones antiguas es agotador...e inútil. Porque es el pasado.
Hay quien afirma y afirmará que el código documentado lo es todo gracias a las habituales "balas de plata": patrones de diseño y arquitectura, buenas prácticas, estándares de desarrollo...Eso está muy bien para pequeños cambios y proyectos no muy antiguos. Pero la realidad es que todo eso ha cambiado en el tiempo. Lo que hoy nos parece la piedra filosofal, mañana estará obsoleto y habrá otros patrones, estándares, etc. Mantener código antiguo nos suele llevar a criticar a su autor, simplemente porque no entendemos las "balas de plata" de aquel momento (bueno, de acuerdo, a veces también hay código antiguo realmente horrendo).
Otro problema está en la dispersión y el tamaño. Está muy bien mantener código con comentarios de módulos pequeños, o sistemas concentrados. ¿Qué ocurre si mi código tiene millones de líneas de código, miles de módulos distribuidos en docenas de aplicaciones? ¿Qué ocurre si no tengo siquiera visibilidad de parte del código o de las aplicaciones porque son de otras empresas?
Aquí de nuevo entran en juego la documentación y los estándares. El primer punto a documentar es siempre las APIs o interfaces. Tanto si son nuestras como si no. Un fallo en el código no sabremos si es porque está mal implantada una API, si está con una versión obsoleta...a no ser que tengamos la documentación actualizada de esa API o interfaz. Los comentarios y la documentación, han de satisfacer objetivos diferentes.
Otra razón ineludible de documentar es la esencia misma de la orientación a objetos: abstracción, encapsulación, etc. Una capa de la arquitectura no puede saber de otra. Lo mismo las funciones o módulos. ¿Entonces cómo rastreo las decisiones que abarcan varios elementos si están dispersos y no saben unos de otros? ¿O es que tengo que hacer un "meta-comentario" (comentario de comentarios)? En realidad, esto que acabo de decir, no es ni más ni menos que la documentación que queremos evitar.
La mejor documentación, es la que está orientada a complementar al código y sus comentarios. Habitualmente, se hace a través de los entregables típicos:
- Requisitos. Recogen a alto nivel las necesidades del sistema desde el punto de vista de cliente/usuario. Son las necesidades básicas. Podemos de alguna forma asimilarlas a las historias de usuario a muy alto nivel. Deben aclarar el qué se espera.
- Análisis funcional: Contienen el qué debe hacerse para lograr lo que espera el cliente. Es suficiente con definir lo que la parte de la documentación de diseño técnico ha de desarrollar.
- Diseño técnico: Si se da trabajo a un programador, un diseño técnico puede contener la resolución a problemas técnicos que se han previsto (los comentarios en el código ya comentan los problemas imprevistos).
¿Estoy diciendo que estos entregables deben hacerse? No, para nada.
¿Tienen que ser 3? Pues tampoco. El hacer 1, 2 o 3 documentos dependerá del contexto. Incluso un breve correo puede ser un análisis funcional de un pequeño cambio. Y no necesitas más. Dependerá de la metodología que se haya definido para el proyecto, el tamaño del mismo, la experiencia...
Lo que digo es que los anteriores son entregables típicos y satisfacen una necesidad. Pero una metodología que obliga de forma rígida (las que por desgracia se implantan en muchísimas empresas), son la causa de las críticas que hay hacia la documentación y hacia las propias metodologías. Si la metodología no se adapta a la realidad del proyecto, será un obstáculo, no un acelerador del trabajo.
¿Cuál es el límite? ¿Hasta dónde documentar? Eso, por desgracia, lo da la experiencia. Yo suelo dar en mis formaciones una máxima: si el analista técnico tiene dudas, es que el funcional necesita más. Si el programador no sabe qué hacer, seguramente el diseño técnico cojea.
Ojo: tampoco quiero decir que no contestemos a la persona que ha de continuar el trabajo. Yo por ejemplo, en un cliente, revisaba la documentación técnica con los programadores, y o bien modificaba el diseño técnico sobre la marcha, o directamente les indicaba cómo quería realizar las cosas, y ellos por un lado, y yo por el otro, seguíamos cada uno haciendo código/documentos. De hecho, algunos programadores terminaban llevando a cabo una solución ligeramente distinta: ellos después me explicaban el motivo, y yo adaptaba el documento a su realidad. Cuesta tiempo llegar a este nivel de colaboración, pero es un placer trabajar así. Das libertad a quien está a pie de teclado soltando código, y al final, lo importante, es que la documentación y el código no se descuadren, y que el equipo sienta que hay cierta libertad de hacer las cosas.
Y un apunte final: todo lo dicho aquí, sirve para cualquier ciclo de vida: cascada, iterativo, RUP, scrum, etc, etc. Siempre alguien tendrá que empezar a trabajar partiendo de algo que le habrán dado: un documento, una servilleta, un post-it en una pizarra...
