Architecture Decision Records

Arquitectura del Software

Cuando se habla de arquitectura de software, hay mucha gente que sinceramente no sabe de qué se habla. Un problema fundamental que tienen muchas personas es que de algún modo creen que la "arquitectura" se refiere a la estructura del proyecto, a su organización o a alguna otra característica más bien estática del proyecto. Así, muchos piensan que la arquitectura de un proyecto es algo que se puede observar directamente en un proyecto en un momento cualquiera.

Por el contrario, hace ya algún tiempo llegué a la conclusión -que seguro que no es una idea original, claro- de que la arquitectura es algo sustancialmente diferente. La Arquitectura es el proceso y el resultado de todas las decisiones "importantes" tomadas a lo largo de la historia del proyecto.

Arquitectura es...

Una vez aceptamos esta perspectiva, surge una pregunta interesante: Todas esas decisiones, ¿dónde quedan documentadas?

Arquitecture Decision Records

Para responder a esto surge la idea de utilizar un formato concreto de documentación. Sí, podríamos documentarlo de muchas maneras y con diferentes formatos y herramientas. Sin embargo, los Registros de Decisión de Arquitectura -ADR, en inglés- proponen una solución sencilla, directa y fácil de manejar.

La idea es la de producir un formato simple, con la información necesaria y nada más. Por supuesto no es ningún tipo de estándar y cada proyecto puede introducir las variaciones que necesite, pero es bueno mantenerlo como algo sencillo y pequeño, con la información necesaria pero solo con esa.

Una propuesta razonable sugiere incluir únicamente cinco partes:

  • Título. Un título descriptivo que explica de qué trata la decisión, e.g. "ADR-1 Despliegue sobre Ruby on Rails v.3.0.10".
  • Contexto. Todos los elementos (técnicos, sociales, personales, etc) del proyecto que intervienen en la toma de la decisión, presentados de forma neutral.
  • Decisión. La respuesta, la decisión que tomamos en ese contexto.
  • Estatus. Una decisión podría estar propuesta o pendiente inicialmente, y después pasaría a estar aceptada. Una decisión también puede estar descartada o reemplazada por otra decisión que se tomó más adelante.
  • Consecuencias. Esta sección sirve para documentar los efectos, tanto positivos como negativos -y neutros-, que se observan después de aplicar la decisión.

Es importante señalar dos cosas. Una, que cada ADR debe ser un documento individual, pero corto. No debería ser necesario llegar a una página y rara vez superarla. Y dos, que los ADRs nunca se borran o eliminan. Ni siquiera cuando una decisión nueva reemplaza la anterior. Se conservan precisamente para tener una documentación completa del progreso del proyecto, de las decisiones que lo han llevado al estado actual. Cuando una decisión supone reemplazar o corregir otra anterior, es importante conservar los registros de ambas decisiones. Es útil relacionar sus ADRs, con una nota o referencia.

Herramientas de ayuda

Realmente podemos aplicar el uso de ADRs en un proyecto sin necesidad de utilizar ninguna herramienta para ello. Es útil, eso sí, definir por lo menos un formato uniforme para los registros -posiblemente con el uso de una plantilla sencilla- e idealmente, algúna nomenclatura para organizar su gestión (puede ser algo tan sencillo como definir una forma de nombrar los ficheros y de guardarlos en directorios).

Pero también puede ser útil utilizar alguna pequeña herramienta de ayuda. Esta, por ejemplo, es poco más que un puñado de scripts de shell. Esta otra es una pequeña utilidad escrita en JavaScript. Como estas existen algunas más. Al final todas son bastante similares y similarmente simples. Como digo pueden ser de ayuda, pero lo más importante es la definición y uso de una plantilla uniforme y el compromiso de mantener los registros de forma constante y continua en el tiempo.

¿Qué conseguimos?

El objetivo final, a estas alturas, debería estar bastante claro. En cualquier momento podemos revisar la historia de las decisiones que se tomaron en un proyecto. Podemos entender el contexto en que se tomaron, evaluar si sigue siendo aplicable o no, si necesitamos una nueva decisión... y sobre todo podemos tener una idea clara de por qué se tomó esa decisión y no otra. Es, probablemente, una de las documentaciones más útiles a la hora de no solo poder entender un proyecto sino también entender cómo ha llegado a ser así.