El arte de crear diagramas de arquitectura

En algún momento, en cada proyecto de software en el que estamos involucrados, podría haber una necesidad de crear diagramas de arquitectura. Tanto si seguimos un modelo arquitectónico formal (por ejemplo, Kruchten 4+1, Rozanski & Woods, etc) como si no, existe la necesidad de documentar algunas partes de la aplicación mediante la creación de diagramas. En la arquitectura de software, tales diagramas se crean de acuerdo con las vistas que están relacionadas con un punto de vista específico que podría ser parte de un modelo, pero en el presente artículo prefiero ceñirme al término diagrama arquitectónico y no ser muy formal; todos los demás aspectos no pretenden ser cubiertos aquí.

Basado en mi experiencia como arquitecto de software y formador técnico, hay una gran cantidad de discrepancias entre los proyectos y dentro del equipo del proyecto de desarrollador a desarrollador en la forma de crear diagramas arquitectónicos. He visto muchos problemas relacionados con la incoherencia, la fragmentación y la granularidad de la información presentada y el aspecto de los diagramas. En comparación con un modelo arquitectónico que debe ser formal y estandarizado, los diagramas pueden no ser necesariamente formalizados o seguir un estándar específico.

Sin embargo, los diagramas deben ser auto descriptivos, consistentes, lo suficientemente precisos y conectados al código. Por eso es importante que todos los arquitectos o ingenieros de software se basen en varias directrices a la hora de crear diagramas de arquitectura, ya que son la base común para comunicar la arquitectura de la aplicación a lo largo del tiempo (por ejemplo, la estructura, los elementos, las relaciones, las propiedades, los principios) y a través de las diferentes partes interesadas que tienen diversos antecedentes técnicos y preocupaciones.

Peligros actuales a la hora de diseñar diagramas de arquitectura

Antes de profundizar en los posibles problemas, me gustaría hacer una analogía con un modismo inglés que dice «una imagen vale más que mil palabras». Según esta explicación de la wiki, «se refiere a la noción de que una idea compleja puede transmitirse con una sola imagen fija o que una imagen de un tema transmite su significado o esencia de forma más eficaz que una descripción». El mismo concepto se aplica a un diagrama arquitectónico: si plantea más preguntas que respuestas, el diagrama no está bien creado. No dejes que un diagrama arquitectónico requiera miles de palabras o aclaraciones!

Ejemplo de un diagrama arquitectónico inadecuado. Sufre la mayoría de los problemas descritos a continuación

Ahora vamos a iterar a través de una lista de escollos que podrían obstaculizar el proceso de creación de diagramas de arquitectura correctamente.

¿Qué denota una caja o forma?

• Usar cualquier tipo de caja o forma que no esté debidamente documentada podría causar múltiples interpretaciones. Puede asociarse a un dato, a un montón de código o a un proceso. Una simple caja en un diagrama puede suscitar múltiples dudas y es muy importante evitarlas añadiendo explícitamente detalles sobre el significado de la caja o forma en la leyenda del diagrama.

¿Qué representan los diferentes bordes de una forma?

• Cada borde de una forma (por ejemplo, punteado, punteado, etc) puede ser malinterpretado en el caso de un diagrama pobre. ¿Un borde específico se refiere a un tipo de componente específico (por ejemplo, una línea discontinua se refiere a un contenedor, un microservicio, una capa, etc.), o es sólo la preferencia del diseñador para tener un aspecto rico? Evite esta confusión proporcionando detalles precisos en el diagrama de la leyenda cuando elija bordes múltiples o no estándar.

¿Qué denota una línea o una flecha?

• Una línea o una flecha puede interpretarse como un flujo de datos (por ejemplo, los datos fluyen desde el sistema A al sistema B) o como una relación entre elementos (por ejemplo, el componente A depende del componente B). En la mayoría de los casos las relaciones o los flujos de datos representados por las flechas no convergen en las mismas direcciones y es importante escribirlo explícitamente en la leyenda del diagrama.

¿Cuál es el tipo de comunicación/asociación indicado por una línea o flecha?

• Incluso si la línea se refiere a un flujo de datos o a una relación a través de los componentes, debe detallarse el tipo de comunicación (por ejemplo, en caso de flujo de datos) o el tipo de asociación (por ejemplo, en caso de relación) denotado por esa línea o flecha. Por ejemplo, si la línea representa un flujo de datos, la comunicación puede ser sincrónica o asincrónica, pero si la línea se refiere a una relación, puede estar representada por una dependencia, herencia, implementación, etc. Todos estos detalles deben estar presentes en la leyenda del diagrama.

¿Qué significa ese color?

• Tener un diagrama policolor «perrot» (por ejemplo, múltiples colores para las cajas, líneas) sin ninguna intención documentada adecuada podría plantear múltiples preguntas (por ejemplo, ¿por qué algunas cajas son verdes y otras rojas? ¿Por qué algunas líneas son negras y otras azules?) El esquema de colores es menos importante en un diagrama, y el uso de un número elevado de colores no aporta demasiado contenido adicional o información valiosa. Un diagrama también podría ser autoexplicativo y estar bien diseñado sólo con el uso de colores blanco y negro, a menos que haya una restricción estricta para enfatizar algunas partes del diagrama mediante el uso de colores distinguibles. En cualquier caso, siempre es mejor ceñirse a la simplicidad en cuanto a los colores utilizados, pero si no es el caso, no olvide detallar la elección.

La falta de relaciones entre los elementos del diagrama o las entidades aisladas

• La falta de relaciones entre los elementos o las entidades aisladas en un diagrama podría ser una pista de que está incompleto. Tanto desde una perspectiva estructural como de comportamiento, cada elemento o entidad debería depender de / tener una relación (representada por una línea o flecha) con otra parte del sistema representada por un elemento diferente.

Acrónimos engañosos/no documentados o términos demasiado vagos/genéricos

• Cuando se utiliza una etiqueta para un elemento en un diagrama, se recomienda no utilizar ningún acrónimo engañoso o no documentado que pueda causar confusiones. Sólo una secuencia de letras (por ejemplo, TFH, RBPM) no significan nada sin una explicación adecuada en el elemento del diagrama o, mejor aún, en la leyenda del diagrama (por ejemplo, TFH – manejador de alimentación de tickets, RBPM – gestor de procesos de negocio de las tasas).

• Otra característica de los elementos del diagrama de nomenclatura se refiere a los términos extremadamente vagos o genéricos (por ejemplo, la lógica de negocio, la lógica de integración) que no aportan demasiada información valiosa porque sus nombres no son adecuadamente auto-descriptivos. Este problema podría residir en el nivel de código también, y la sugerencia sería utilizar siempre nombres autoexplicativos y sugerentes siguiendo los principios de código limpio.

Enfatizar tecnologías, marcos, lenguajes de programación o scripting, IDE o metodología de desarrollo en los diagramas

• El diseño arquitectónico no está relacionado ni se basa fundamentalmente en ninguna tecnología, marco, lenguaje de programación o scripting, IDE o metodología de desarrollo. Todos ellos vienen después en el proceso para ayudar a construir la arquitectura, pero no son el punto central. No deben incluirse en los diagramas, sino que deben indicarse en la descripción de la arquitectura, incluyendo la justificación de su elección.

Mezclar elementos de tiempo de ejecución y estáticos en el mismo diagrama

• Los elementos de tiempo de ejecución (por ejemplo, hilos, procesos, máquinas virtuales, contenedores, servicios, cortafuegos, repositorios de datos, etc.) no están presentes en tiempo de compilación y se recomienda evitar mezclar estos elementos con los estáticos (por ejemplo, componentes, paquetes, clases) en el mismo diagrama. Hay tipos de diagramas dedicados (por ejemplo, diagrama de concurrencia, diagrama de despliegue) que se centran principalmente en los elementos de tiempo de ejecución y es importante distinguir entre estas dos categorías de elementos y evitar mezclarlos en la medida de lo posible.

Hacer suposiciones como «describiré esto verbalmente», y «lo explicaré más tarde»

• Todo lo que no está descrito por el propio diagrama está ausente, y no hay espacio para proporcionar detalles verbales para complementar un diagrama. ¿Por qué? Porque todas las explicaciones mencionadas oralmente pero no plasmadas en el diagrama se pierden, y más tarde, cuando algunos otros interesados (por ejemplo, el desarrollador, el arquitecto) lean el diagrama, no serán conscientes de estas explicaciones. Trate de incluir todos los detalles necesarios en un diagrama para evitar cualquier necesidad de aclaraciones adicionales.

Niveles conflictivos de detalles o abstracciones mixtas

• Añadir elementos relacionados con diferentes niveles de abstracción en el mismo diagrama podría entrar en conflicto, ya que se ven desde diferentes perspectivas. Por ejemplo, añadir componentes a un diagrama de contexto arquitectónico o clases a un diagrama de despliegue podría divergir el propósito del propio diagrama. Al crear un diagrama, trate de mantener el mismo nivel de abstracción.

Diagramas desordenados o demasiado vagos que tratan de mostrar un nivel de detalle excesivo o insuficiente

• «Todo debe hacerse tan simple como sea posible, pero no más simple» es una cita bien conocida que pertenece a Albert Einstein. Esto es válido también para los diagramas de arquitectura; el nivel y la granularidad de la información capturada deben ser elegidos de forma significativa. Esto no es algo fácil; depende del modelo arquitectónico utilizado, de la experiencia del arquitecto y de la complejidad del sistema.

Directrices a seguir en la creación de diagramas de arquitectura

Además de los escollos anteriores, que deben formar parte de una lista de comprobación previa para evitarlos, también hay directrices generales sobre cómo crear correctamente los diagramas:

Elegir el número óptimo de diagramas

• Como dijo Philippe Kruchten, «la arquitectura es una bestia compleja. Utilizar un solo plano para representar la arquitectura da como resultado un lío semántico ininteligible.» Para documentar los sistemas modernos no podemos acabar con un solo tipo de diagrama, pero a la hora de crear diagramas de arquitectura no siempre es sencillo qué diagramas elegir y cuántos de ellos crear. Hay múltiples factores que hay que tener en cuenta antes de tomar una decisión; por ejemplo, la naturaleza y la complejidad de la arquitectura, las habilidades y la experiencia del arquitecto de software, el tiempo disponible, la cantidad de trabajo necesario para mantenerlos y lo que tiene sentido o es útil para satisfacer las preocupaciones de las partes interesadas. Por ejemplo, un ingeniero de redes probablemente querrá ver un modelo de red explícito que incluya hosts, puertos de comunicación y protocolos; a un administrador de bases de datos le preocupa cómo el sistema manipula, gestiona y distribuye los datos, etc. Basándose en todos estos aspectos, se recomienda escoger el número óptimo de diagramas, sea cual sea ese número.
• Si hay un número insuficiente de diagramas (por ejemplo, subdocumentación), partes de la arquitectura podrían quedar ocultas o sin documentar; por otro lado, si hay demasiados (por ejemplo exceso de documentación), el esfuerzo necesario para mantenerlos consistentes, actualizados y no fragmentados podría aumentar considerablemente.

Mantener la consistencia estructural y semántica entre los diagramas

• Cada diagrama debe ser consistente con los demás en términos de cajas, formas, bordes, líneas, colores, etc. El aspecto estructural debe ser el mismo y cada parte interesada no debe tener dificultades para entender los diagramas creados por diferentes desarrolladores dentro de un equipo. Lo ideal es utilizar una herramienta de diagramación común y reutilizarla en todos los proyectos.
• Desde el punto de vista semántico, todos estos diagramas deberían sincronizarse periódicamente con los últimos cambios de código y entre ellos, ya que un cambio en un diagrama podría afectar a otros. Este proceso puede ser activado manualmente o automáticamente mediante el uso de una herramienta de modelado. Este último es el mecanismo preferido, pero depende de cada proyecto; en todos los casos, la idea es mantener la coherencia entre los diagramas y el código, independientemente del método o la herramienta. Simon Brown dijo que «los diagramas no son útiles para la mejora de la arquitectura si no están conectados con el código», lo que enfatiza la idea de la consistencia semántica.

Prevenir la fragmentación de los diagramas

• Tener múltiples diagramas podría dificultar la comprensión de la descripción arquitectónica pero también un esfuerzo importante en su mantenimiento. Como efecto secundario, podría aparecer la fragmentación (por ejemplo, dos o más diagramas ilustran el mismo atributo de calidad – rendimiento, escalabilidad, etc. – pero cada uno de ellos está individualmente incompleto). En estos casos se recomienda eliminar los diagramas que no reflejan los atributos de calidad relevantes (vinculados a los requisitos arquitectónicos significativos) o, incluso mejor, fusionar los diagramas (por ejemplo, la concurrencia y el despliegue).

Mantener la trazabilidad a través de los diagramas

• Para ser capaz de comprobar la historia, hacer comparaciones entre las diferentes versiones de los diagramas además de revertir fácilmente a una versión anterior también es importante. Utilizar una herramienta de modelado que no permita eso puede ser un impedimento. Las últimas tendencias en la industria se basan en el uso de un lenguaje de texto simple e intuitivo para generar los diagramas, lo que parece resolver la preocupación por la trazabilidad. Otra ventaja de este enfoque es que asegura implícitamente una consistencia estructural homogénea entre los diagramas.

Agregar leyendas junto a los diagramas de arquitectura

• Si no sigue un lenguaje de descripción arquitectónica estándar (por ejemplo, UML, ArchiMate), detalle cada pieza del diagrama en la leyenda (por ejemplo, cajas, formas, bordes, líneas, colores, acrónimos, etc).
• Si este no es el caso, en la leyenda sólo hay que añadir el lenguaje de descripción arquitectónica como una clave y no hay necesidad de explicaciones adicionales, ya que cada lector seguirá en ese lenguaje específico para entender el diagrama.

¿El Lenguaje de Descripción Arquitectónica (por ejemplo, UML, ArchiMate, etc.) hace una diferencia?

Hay muchas opiniones con respecto a cuál es el lenguaje de descripción adecuado para ser adoptado en el proyecto. Algunas personas podrían argumentar que UML es rígido y no lo suficientemente flexible para modelar el diseño arquitectónico, un punto de vista con el que estoy de acuerdo. Sin embargo, en algunos casos puede ser más que suficiente para documentar los fundamentos de una arquitectura sin depender de ninguna característica de extensibilidad de UML como los perfiles y los estereotipos. Echando un vistazo a otros lenguajes de descripción, podemos ver que ArchiMate es más potente y adecuado para modelar sistemas empresariales en comparación con UML; también está BPMN, que está particularmente dirigido a los procesos de negocio, etc. Las comparaciones podrían continuar, pero no pretendo hacer una revisión profunda a través de ellos, ya que no es el objetivo de este artículo.

Tener un lenguaje de descripción arquitectónica lo suficientemente completo y flexible es un gran paso adelante y esto debería ser un criterio sólido a la hora de elegirlo. Pero desde mi punto de vista, la verdadera causa reside en otro lugar y está relacionada con el hecho de que la documentación arquitectónica no se crea en absoluto. La gente suele considerar que crearla es aburrido, inútil o sin sentido. El número de proyectos de software sin, o con una documentación inadecuada, es enorme. No creo que la gente esté creando o participando intensamente en la creación de diagramas arquitectónicos utilizando un lenguaje de descripción inadecuado, y si lo sustituyeran por uno mejor los resultados serían muy diferentes. No, la gente no está creando ninguna documentación arquitectónica (incluidos los diagramas arquitectónicos) y, lo que es peor, la mayoría no tiene ni idea de cómo crearla correctamente. Estas son las cosas que tenemos que abordar en primer lugar: entender por qué la documentación es importante y cómo crearla adecuadamente (formando a los ingenieros de software); entonces la selección de las herramientas adecuadas surge de forma natural.

¿Cómo se pueden mantener actualizados los diagramas a medida que se desarrolla el sistema, y se materializan los cambios en la arquitectura

Hay pocos enfoques para mantener actualizados los diagramas; a continuación expresaré tres de ellos. La primera opción, y la más sencilla, sería generar automáticamente los diagramas a partir del código fuente, que es la verdad de base. Esto garantiza que todos sean coherentes con el código. Desgraciadamente, con las herramientas existentes esto todavía no es totalmente posible (al menos que yo sepa), ya que las herramientas actuales no pueden crear ningún tipo de diagrama preciso y significativo sólo a partir del código fuente, sin una importante intervención manual. Len Bass dijo que «el entorno de desarrollo ideal es aquel para el que la documentación está disponible de forma esencialmente gratuita con sólo pulsar un botón», generando implícitamente los diagramas de forma automática, pero no hemos llegado a ese punto.

El segundo enfoque sería diseñar primero los diagramas utilizando una herramienta dedicada que luego genere los esqueletos de código fuente (por ejemplo, componentes/paquetes con límites, APIs) utilizados posteriormente por los desarrolladores para rellenar el código. De esta manera, cada cambio en la arquitectura debe ser activado desde el propio diagrama que automáticamente podría regenerar o actualizar el esqueleto de código.

El último caso implica la actualización manual de los diagramas cada vez que una nueva característica – que tiene un impacto en el diseño arquitectónico – se implementa. Para asegurarse de que todos los cambios de código se reflejan en los diagramas, se recomienda que la actualización de los diagramas para ser parte de la definición de hecho en el proceso de desarrollo. Este escenario es menos recomendable porque podría causar fácilmente diagramas obsoletos o inconsistentes (por ejemplo, los desarrolladores a menudo se olvidan o no están de humor para actualizar los diagramas) y, por desgracia, esto sigue ocurriendo en la mayoría de los proyectos.

Tomando en cuenta las herramientas existentes, mi recomendación es tener una mezcla; mezclar automáticamente y manualmente la creación de diagramas. Por ejemplo, tratar de autogenerar diagramas, que pueden ser razonablemente representados por herramientas basadas en el código fuente sin demasiado ruido (por ejemplo, información demasiado desordenada o sin sentido). En esta categoría podemos incluir los diagramas con un alto grado de volatilidad (por ejemplo, más propensos a los cambios frecuentes de desarrollo, que suelen tener una abstracción menor) o, por el contrario, los diagramas estáticos. Algunos de estos diagramas podrían referirse a diagramas de contexto, diagramas de arquitectura de referencia, diagramas de paquete, diagramas de clase, diagramas de entidad, etc. Sin embargo, en algunos casos, no es evidente, basándose únicamente en el código fuente, cómo el sistema cumple con algunos atributos de calidad (por ejemplo, disponibilidad, escalabilidad, rendimiento), por lo que la creación automática de diagramas no es una opción suficiente. Es necesario complementarla con diagramas modelados manualmente. Algunos ejemplos de tales diagramas incluyen diagramas de secuencia, diagramas de estado, diagramas de concurrencia, diagramas de despliegue, diagramas operacionales, etc.

¿Qué complicaciones (o simplificaciones) surgen para los diagramas de arquitectura cuando se trata de arquitecturas modernas (e.

Los microservicios o cualquier otro estilo arquitectónico moderno (por ejemplo, sin servidor, impulsado por eventos) sólo impulsa la estructura del sistema, cómo los componentes se comunican entre sí (por ejemplo, las relaciones entre ellos) y qué principios los rigen. Personalmente, no creo que el estilo arquitectónico deba cambiar la lógica o los conceptos en torno a la creación de los diagramas (e implícitamente la descripción arquitectónica), ni lo que deben capturar. Sin embargo, cuando hablamos de arquitecturas de sistemas modernos, que suelen tener mayores niveles de complejidad en comparación con los sistemas antiguos y clásicos (por ejemplo, monolitos), definitivamente tienen un impacto en la descripción arquitectónica e implícitamente en los diagramas, en el sentido de que hay múltiples consideraciones a tener en cuenta. Dichas consideraciones podrían ser en cuanto a la comprensión del número de componentes distribuidos (por ejemplo, micro-servicios distribuidos), el tipo de cada componente, cómo los componentes se comunican entre sí (por ejemplo, límites, APIs, mensajes), su ciclo de vida y quién es el dueño de cada componente.

Tomando todo esto en cuenta, las vistas que capturan la descomposición del sistema, el desarrollo, el despliegue y la operatividad deben ser consideradas por defecto. Imagina un sistema con un número impresionante de microservicios, por ejemplo; en tal caso el número de diagramas podría aumentar significativamente porque cada microservicio podría acabar teniendo su propio conjunto de diagramas. Las cuestiones relativas a la coherencia (por ejemplo, el cambio de la API de un servicio afecta a otros X servicios, por lo que todos los diagramas afectados deben ser actualizados), la fragmentación (por ejemplo, la alta disponibilidad o el rendimiento entre los servicios distribuidos no se consolida en un diagrama) o las preocupaciones transversales (por ejemplo, quién es el encargado de ilustrar, de manera consolidada, aspectos como la supervisión o la seguridad en todos los elementos del sistema) podrían no ser fáciles de manejar. Además, puede haber problemas relacionados con la coexistencia y la colaboración de los equipos durante el desarrollo del proyecto, e incluso después, para mantenerlo.

En resumen, los sistemas modernos con arquitecturas complejas pueden plantear problemas adicionales que pueden dar lugar a complicaciones incluso a nivel de los diagramas.

Acerca del autor

Ionut Balosin es arquitecto de software y formador técnico independiente. Es un ponente habitual en conferencias y encuentros de desarrollo de software en todo el mundo, realizando presentaciones, cursos de formación y talleres. Para más detalles, consulte su sitio web.