Dentro de un año alguien abrirá el proyecto y se preguntará por qué hay una cola de mensajes donde habría bastado una llamada directa. Si nadie escribió el motivo, la elección se repetirá, se deshará o, peor, se defenderá sin saber por qué. Documentar no significa escribir mucho: significa registrar lo que el código por sí solo no dice.
Qué no dice el código
El código dice qué hace el sistema. No dice por qué se eligió un camino en lugar de otro, qué restricciones había, qué alternativa se descartó y por qué. Este es el contenido que se pierde primero cuando cambian las personas.
Las decisiones arquitectónicas (ADR)
Un ADR (Architecture Decision Record) es una nota breve, una por decisión, que contiene:
- Contexto: el problema y las restricciones del momento.
- Decisión: qué se ha elegido.
- Alternativas consideradas: y por qué no se eligieron.
- Consecuencias: qué resulta más fácil, qué más difícil, qué riesgos se aceptan.
- Estado: propuesta, aceptada, sustituida por otra decisión.
Se escribe en el momento en que se decide, cuando el razonamiento está fresco. No se reescriben: una decisión cambiada se registra con una nota nueva que sustituye a la anterior, así queda la historia.
Se escribe un ADR cuando la elección es difícil de deshacer, afecta a varias partes del sistema, o cuando alguien, en el futuro, se preguntará razonablemente «pero ¿por qué?».
Documentación de API y funcionalidades
Para quien usa una interfaz importan: para qué sirve, un ejemplo que funcione, los parámetros con sus restricciones, los errores posibles y qué hacer. La documentación que se puede ejecutar (ejemplos probados) envejece mejor que la meramente descriptiva. Cuando se modifica una API pública, se actualiza la documentación en el mismo cambio.
Comentarios en el código
Un comentario que repite el código es ruido. Un comentario útil explica el porqué de una anomalía: «aquí se redondea a la baja porque el proveedor trunca». También se señalan las restricciones poco obvias y los casos que el código protege. Cuando el código cambia, el comentario cambia con él, o se borra.
Para quien lea: personas y agentes
La documentación sirve también a los agentes que trabajarán en el proyecto: un archivo de reglas, decisiones escritas y un índice por área los hacen más fiables, por la misma razón por la que ayudan a un nuevo compañero.
Dónde guardar la documentación
Cerca del código, en el mismo repositorio, revisada en los mismos cambios. La documentación en otro sitio, actualizada aparte, se desfasa casi enseguida.
Señales de alarma
- Decisiones importantes guardadas solo en la memoria de alguien.
- Comentarios que describen lo que hace el código en lugar del porqué.
- Documentación que no ha cambiado mientras cambiaba la API.
- ADR reescritos en lugar de sustituidos.
- Ningún rastro de las alternativas descartadas.
Un ejemplo
Un equipo decide no usar una base de datos relacional para un módulo. Nota escrita el mismo día: contexto (muchos datos semiestructurados, escrituras frecuentes), decisión, alternativas consideradas (la base de datos relacional ya en uso, descartada por el coste de las migraciones de esquema), consecuencias (las consultas transversales son más difíciles). Dos años después, un nuevo compañero entiende la elección en dos minutos y sabe cuándo merece la pena revisarla.
Cuándo usarlo
Al tomar decisiones arquitectónicas, cambiar API públicas, lanzar una funcionalidad o cuando hace falta registrar un contexto que los futuros desarrolladores y agentes tendrán que conocer.
Este método deriva de la familia de skills de código abierto agent-skills de Addy Osmani (licencia MIT), reescrita y adaptada.
Este artículo es una skill de OIAR
Lo que acabas de leer es el contenido de una skill del catálogo de OIAR, escrito para las personas. Un conocimiento como este pero más rico y profundo, escrito para los agentes, guía las entrevistas, el análisis y el informe dentro de la plataforma. Las skills se usan en OIAR: para probarla en un proyecto tuyo necesitas una cuenta.
documentation-and-adrsMétodo para registrar el porqué de las elecciones técnicas: ADR (contexto, decisión, alternativas, consecuencias, estado), documentación de API y funcionalidades con ejemplos, comentarios que explican el motivo. Úsese al tomar una decisión arquitectónica, cambiar una API pública o lanzar una funcionalidad.