arc42 y otras plantillas de documentación

Qué es arc42

arc42 es una plantilla gratuita para describir y comunicar la arquitectura de software, creada por Gernot Starke y Peter Hruschka y usada en la práctica desde 2005. Se publica bajo una licencia Creative Commons Attribution-ShareAlike (Reconocimiento-CompartirIgual), en más de una docena de idiomas y en formatos como AsciiDoc, Markdown y Word, con una versión simple y otra con texto de ayuda integrado. Está especialmente extendida en los países de habla alemana y en la formación de iSAQB, pero se usa en todo el mundo.

arc42 no es, deliberadamente, ni un método ni una notación. No te dice cómo diseñar ni prescribe UML, C4 ni ningún otro estilo de diagrama. Es un conjunto de doce cajones etiquetados: para cada tipo de información arquitectónica, dice dónde ponerla, para que todo lector sepa dónde buscar y todo autor sepa qué falta. Sus autores dejan claro que todas las secciones son opcionales; un sistema pequeño puede completar cuatro secciones en unas pocas páginas, y uno grande puede completar las doce en muchas.

La plantilla se basa en ideas vistas antes en este capítulo. Sus tres vistas (bloques de construcción, tiempo de ejecución y despliegue) se corresponden de cerca con las categorías de módulos, de componentes y conectores y de asignación del SEI, y con las vistas de desarrollo, de procesos y física de Kruchten de vistas y puntos de vista. Su sección de decisiones es donde van los registros de decisiones de arquitectura, y su sección de calidad es donde van los escenarios de atributos de calidad del Capítulo 2.

Las doce secciones

El diagrama agrupa las secciones según la pregunta que responden. Las secciones 1 a 3 fijan los objetivos y los límites: para qué sirve el sistema, qué limita la solución y dónde termina el sistema. La sección 4 enuncia las ideas fundamentales de la solución, y las secciones 8 y 9 contienen los principios y las decisiones que se aplican a toda ella. Las secciones 5 a 7 muestran la estructura desde tres ángulos. Las secciones 10 a 12 hacen explícitos la calidad, el riesgo y el vocabulario.

Usar arc42 de forma ligera

La forma más común de fracasar con arc42 es tratarla como un formulario que hay que rellenar: se crean doce encabezados, cada uno se llena con algo, y el resultado es largo, genérico y nunca se lee. Las propias indicaciones de la plantilla apuntan en la dirección contraria. Las FAQ de arc42 dicen que no hay una regla general para el mínimo, porque depende de la criticidad, el tamaño, la complejidad y el riesgo, pero sugieren que incluso una descripción mínima debería contener de tres a cinco requisitos de calidad centrales en forma de escenarios, el contexto y las interfaces externas, una breve estrategia de solución, la vista de bloques de construcción de nivel 1 y los conceptos transversales más importantes.

Cuatro hábitos mantienen arc42 ligera. Elimina las secciones vacías o márcalas de forma deliberada (Despliegue: una única plataforma gestionada; ver el repositorio de infraestructura), para que el lector sepa que el hueco es intencionado. Enlaza en lugar de copiar: los requisitos viven en el backlog, las decisiones en la carpeta de ADR, el despliegue en la infraestructura como código; arc42 apunta a ellos. Prefiere diagramas con tablas breves de elementos a páginas de prosa. Escribe para las preguntas del próximo lector, no por exhaustividad: si nadie va a preguntar por el comportamiento en tiempo de ejecución de las pantallas de administración, no lo describas.

arc42 se combina bien con el modelo C4. Una combinación habitual es un diagrama de contexto del sistema de C4 en la sección 3, un diagrama de contenedores como nivel 1 de la vista de bloques de construcción en la sección 5, con diagramas de componentes como nivel 2, y un diagrama de despliegue de C4 en la sección 7. Si se mantienen como diagramas como código en el mismo repositorio que el texto de arc42, toda la descripción puede versionarse y revisarse como el código.

Ejemplo práctico: arc42-lite para la plataforma de reparto de comida

La página de abajo es una descripción arc42-lite completa de la plataforma de reparto de comida que se usa a lo largo de este capítulo. Cabe en una página impresa más el diagrama de contexto y, aun así, responde a las preguntas que haría primero un nuevo ingeniero, un responsable de operaciones o un auditor, y señala dónde está el detalle.

Otras plantillas

La plantilla Views and Beyond del SEI. El Software Engineering Institute publica una plantilla de documentación que sigue Documenting Software Architectures: Views and Beyond, de Paul Clements y sus colegas. Su nivel superior tiene seis partes: una hoja de ruta y una visión general de la documentación, los antecedentes de la arquitectura, las vistas, la correspondencia entre vistas, los materiales de referencia y un glosario con siglas. Cada vista se documenta de la misma manera, con una presentación principal, un catálogo de elementos, un diagrama de contexto, una guía de variabilidad y la justificación (descritos en el recuadro "Para profundizar" de la Sección 4.2). Es más exhaustiva que arc42 y conviene a sistemas grandes, de larga vida o especificados por contrato, en los que cada vista debe estar completa y con referencias cruzadas; su correspondencia entre vistas es un punto fuerte que arc42 deja implícito.

IEEE 1016. IEEE Std 1016-2009, Software Design Descriptions, especifica el contenido y la organización de una descripción del diseño de software (SDD), el documento de diseño detallado que tradicionalmente se exige en defensa, en la industria aeroespacial y en otros proyectos regidos por contrato. Tomó de IEEE 1471 (el predecesor de 42010) los conceptos de parte interesada, inquietud, punto de vista y vista, y enumera puntos de vista de diseño como contexto, composición, lógico, dependencia, información, interfaz, interacción, dinámica de estados, algoritmo y recursos. IEEE la pasó al estado inactive-reserved (inactiva reservada) en 2020, pero todavía se cita en contratos y en la docencia, y programas más antiguos siguen entregando SDD con su forma. Está más cerca del diseño detallado que de la arquitectura.

Los documentos de diseño y los RFC, que usan muchas organizaciones de ingeniería, son otro tipo de plantilla: una propuesta para un cambio concreto en lugar de una descripción de todo un sistema. Se tratan dos secciones más adelante, en comunicar la arquitectura.

Conformidad con ISO/IEC/IEEE 42010

ISO/IEC/IEEE 42010:2022 establece requisitos para las descripciones de arquitectura y para los marcos de descripción de arquitectura (ADF): convenciones establecidas, como arc42 o el enfoque Views and Beyond, para producir descripciones en una comunidad determinada. No prescribe una plantilla, una notación ni un proceso. Una descripción es conforme cuando contiene la información que exige la norma, sea cual sea la plantilla que la organice.

En términos generales, eso significa identificar el sistema descrito y su entorno, identificar las partes interesadas y sus inquietudes, indicar qué puntos de vista se usan y qué inquietudes enmarca cada uno, proporcionar vistas que sigan esos puntos de vista, registrar las correspondencias (cómo se relacionan los elementos de distintas vistas) y registrar la justificación de las decisiones clave. arc42 no afirma ser conforme de serie, y las descripciones arc42 sin más a menudo carecen de un vínculo explícito entre cada inquietud y la vista que la aborda. Las carencias son pequeñas y fáciles de cubrir, como muestra la tabla. La mayoría de los equipos no necesitan una conformidad formal; los de sectores regulados o vinculados por contrato a veces sí, y es tranquilizador que una plantilla ligera pueda cumplir la norma con unos pocos añadidos.