Documentar sí, pero ágil

Bonanjo_-_Centre_de_documentation_et_information_urbanisme_(CUD)_05

Uno de los temas más polémicos cuando hablamos de metodologías ágiles es la documentación. Documentar ¿Sí o No? A esta pregunta se suma uno de los puntos del manifiesto ágil que nos dice: “software que funcione, por encima de documentación exhaustiva”

Hay dos problemas fundamentales que ha arrastrado siempre la documentación relacionada con el desarrollo de Software.

  1. Documentación extensa: Entramos a un proyecto y nos encontramos con 400 páginas de documentación que son casi imposible de leer y entender. Aún así, vamos a suponer que tenemos un alto grado de abstracción y logramos entender cómo debería funcionar ese Software basado en esa documentación, al abrir el proyecto nos encontramos con el segundo problema.
  2. Documentación desactualizada: Somos desarrolladores, la fase superior del vago. Si dentro del propio código nos cuesta un enorme trabajo actualizar un comentario referente a una lógica que acabamos de modificar, imagina si esa documentación está en un documento Office almacenado en la nube en la carpeta… ¿cuál era? y con nombre… ¿cuál era?

Estos problemas son los que se intentan evitar cuando en el manifiesto ágil dan mayor importancia a que el Software funcione. Toda documentación que no se lee o queda desactualizada, es tiempo y esfuerzo perdido. Ahora bien, esto NO significa que la documentación desaparece. En la explicación del propio manifiesto ágil se indica que, cito: “aunque valoramos los elementos de la derecha, valoramos más los de la izquierda

La solución pasa por documentar puntos estratégicos de nuestro proyecto sin caer en los problemas mencionados anteriormente. Primero, documentación clara y concisa, nada de escribir un Quijote, y segundo, esta documentación debería persistir lo más posible en el tiempo y mantener su validez, sin necesidad de ser actualizada.

¿Qué y cómo deberíamos documentar?

Arquitectura
La arquitectura en un proyecto “debería” cambiar poco. Si seguimos diseños como Three-Tier o N-Tier, DDD, CQRS, Microservices, etc. Tendríamos un 80% de la documentación de este punto ya hecha y, solo nos quedaría documentar aquellos aspectos que hemos hecho de manera diferente.

Clases y métodos
Cero comentarios dentro de métodos o propiedades. Con comentar la cabecera de la clase y la cabecera de cada uno de los métodos incluyendo sus parámetros, debería ser suficiente.

Para la documentación de clases y métodos, usar un resumen corto y claro que nos diga qué se hace y no cómo se hace. De esta manera logramos que, si se cambia la lógica del método o se adicionan nuevos métodos a una clase, no tengamos que actualizar la documentación.

Actualización: Después de un corto pero buen debate con Juanma y Joaquín sobre este punto, creo necesario aclarar que la documentación en clases y métodos, puede incluso no ser necesaria. Para esto, es necesario lograr una buena elección de nombres capaces de indicarnos qué hace la clase o el método.

Dejo un artículo del propio Juanma sobre este tema: “Por favor, comenta el código“. Aunque el concepto del “por qué” lo veo interesante,  intentaría llevar el comentario a nivel de método y no incluirlo en el código.

¿Y la lógica?
Para la lógica no hay mejor documentación que el propio código. Si revisas un código escrito un mes atrás, y no eres capaz de saber lo que hiciste, malo.  Una buena programación orientada a objetos (que no es lo mismo que programar en un lenguaje orientado a objetos) puede salvarnos de estos problemas.

En los primeros pasos de un proyecto, herramientas de análisis de código nos pueden ser de mucha ayuda, con ellas podemos detectar qué se está haciendo mal y orientar las formaciones o debates hacia estos problemas.

Salu2 c.u

Esta entrada fue publicada en Ágil, Clean Code. Guarda el enlace permanente.

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *