Este artículo puede incluir enlaces de afiliado. Si compras a través de ellos, me llevo una pequeña comisión sin coste extra para ti. Más información.
Durante años tuve una libreta cuadriculada al lado del teclado. No era decoración. Antes de escribir una sola línea de código, dibujaba. Cajas, flechas, clases con sus métodos apuntando a otras clases. Un lío de tinta que solo yo entendía, pero que me servía para pensar.
Hace unos meses dejé de hacerlo. Empecé a generar los diagramas directamente desde el código Java, con herramientas que leen tus clases y te escupen un UML decente en segundos. Y funciona. Vaya si funciona.
Pero llevo un tiempo con una sensación rara. Como cuando cambias de un coche manual a uno automático y de repente conduces sin enterarte del camino. Este artículo va de eso: de lo que se gana automatizando los diagramas, y de lo que en silencio se pierde.
Por qué acabé generando diagramas desde el código Java
La razón principal fue vergonzosamente práctica: los diagramas dibujados a mano envejecen mal. Muy mal.
Dibujas una arquitectura preciosa un lunes. El miércoles refactorizas media aplicación. El viernes ese diagrama ya miente. Y un diagrama que miente es peor que no tener diagrama, porque alguien confiará en él.
En proyectos con varias personas esto se multiplica. Documentar la arquitectura a mano en un equipo que mueve código a diario es como pintar una raya en el agua. Te cansas y dejas de hacerlo.
Así que la idea de generar el diagrama desde la verdad, que es el código, tenía todo el sentido. Si el código cambia, el diagrama cambia. No hay margen para la mentira.
Baeldung tiene un artículo bastante completo sobre generar diagramas desde Java que me sirvió de punto de partida para ordenar opciones. Recomiendo leerlo si te interesa el tema, porque cubre varias herramientas con ejemplos concretos.
Las herramientas que probé
No voy a hacer una lista exhaustiva porque hay demasiadas y muchas se solapan. Pero sí las que de verdad usé en algo real.
PlantUML fue la primera. Técnicamente no genera desde el código, tú escribes un texto plano que describe el diagrama. Pero ese texto vive en el repositorio, se versiona con Git, y para mí eso ya fue un salto enorme.
Después probé herramientas que sí leen el bytecode o el código fuente y generan el diagrama solas. Ahí están cosas como PlantUML con parsers, plugins de IntelliJ, y para arquitectura de más alto nivel me enganché a Structurizr, que sigue el modelo C4.
El enfoque de Structurizr me gustó especialmente porque no describes clases sueltas, describes el sistema en niveles: contexto, contenedores, componentes. Defines eso en Java, con su DSL, y él pinta.
El diagrama que se escribe a sí mismo
Lo que más me sorprendió fue meter la generación de diagramas dentro del propio flujo de código. No como un paso manual, sino como algo que ocurre solo.
Con Structurizr, por ejemplo, defines tu modelo de arquitectura como código Java normal. Y ese código se ejecuta, y produce la definición del diagrama. Te dejo un fragmento reducido para que se vea la idea.
Workspace workspace = new Workspace("Tienda", "Modelo de la tienda online");
Model model = workspace.getModel();
Person cliente = model.addPerson("Cliente", "Compra libros de gatos");
SoftwareSystem tienda = model.addSoftwareSystem("Tienda", "Vende libros");
SoftwareSystem pagos = model.addSoftwareSystem("Pasarela de pagos", "Cobra");
cliente.uses(tienda, "Navega y compra");
tienda.uses(pagos, "Procesa el pago");
ViewSet views = workspace.getViews();
SystemContextView contextView = views.createSystemContextView(
tienda, "contexto", "Vista de contexto del sistema");
contextView.addAllElements();Eso, ejecutado, te describe quién habla con quién a nivel de sistema. No estás dibujando cajas, estás declarando relaciones. Y de esas relaciones sale el dibujo.
La diferencia mental es sutil pero importante. Cuando dibujas a mano, decides cómo se ve. Aquí decides qué es cierto y la herramienta decide cómo se ve. Le cedes el diseño visual a cambio de que nunca mienta.
Y en un pipeline de integración continua esto se vuelve casi mágico. Cada vez que se hace un merge, se regeneran los diagramas. La documentación deja de ser una foto vieja y pasa a ser un espejo.
Cuándo esto es claramente mejor
Hay contextos donde no hay debate. Si tienes un sistema grande, con muchas clases y muchas dependencias, dibujar eso a mano es imposible y mantenerlo, un suicidio.
Para explicar a alguien nuevo cómo está montado el proyecto, un diagrama generado y actualizado vale oro. Le enseñas algo que es verdad hoy, no lo que era verdad hace seis meses.
Y para auditar dependencias raras, esas flechas que no deberían existir entre paquetes que no deberían conocerse, la generación automática las saca a la luz sin piedad. El dibujo a mano tiende a ocultar lo feo. El generado lo enseña todo.
Lo que se pierde cuando dejas de pensar con lápiz
Aquí viene la parte incómoda. Porque todo lo anterior es cierto, y aun así siento que perdí algo.
Cuando dibujaba un diagrama antes de programar, no estaba documentando. Estaba pensando. El acto de decidir qué caja va arriba, qué flecha sale de dónde, me obligaba a entender el sistema antes de existir.
El diagrama generado no hace eso. Genera desde algo que ya existe. Llega tarde. Te documenta las decisiones, pero no te ayuda a tomarlas.
Y me di cuenta de que había empezado a programar sin diseñar. Escribía clases, las conectaba, y luego generaba el diagrama para ver qué había hecho. Como quien construye una casa y luego dibuja los planos para averiguar dónde están las paredes.
«El diseño no es solo cómo se ve o cómo se siente. El diseño es cómo funciona.»
— Steve Jobs
Esa frase la repiten hasta el aburrimiento, pero encaja aquí. Un diagrama generado te muestra cómo se ve tu sistema. No te ayuda a decidir cómo debería funcionar. Esas dos cosas se habían fundido en mi cabeza y no eran lo mismo.
El lápiz me forzaba a lo segundo. La herramienta solo me da lo primero. Y confundir una cosa con la otra es fácil cuando la máquina te da un resultado bonito con cero esfuerzo.
El pensamiento lento tiene su valor
Dibujar es lento. Ese es su defecto y su virtud a la vez.
La lentitud te obliga a descartar. Si dibujar una relación cuesta, te lo piensas dos veces antes de crearla. Cuando el código genera el diagrama solo, no hay fricción, y sin fricción metes dependencias que quizá no deberían estar.
Cómo lo hago ahora: un término medio
No he vuelto a la libreta del todo. Sería mentir y quedar de romántico insufrible. Pero he cambiado la forma de usar cada cosa.
Ahora dibujo antes, para pensar. Y genero después, para documentar. Son dos momentos distintos con dos propósitos distintos, y mezclarlos fue mi error.
Antes de escribir código para una funcionalidad nueva, saco la libreta o abro una pizarra digital y dibujo lo justo. No busco precisión. Busco entender. Ese dibujo lo tiro después, no lo guardo. Su valor estaba en el proceso, no en el resultado.
Luego, cuando el código existe, dejo que las herramientas generen la documentación viva. Esa sí se queda, se versiona y se actualiza sola en cada build.
El truco fue dejar de pedirle a una sola cosa que hiciera los dos trabajos. El lápiz piensa. La máquina documenta. Y ninguno de los dos hace bien el trabajo del otro.
Un detalle sobre mantener el diagrama honesto
Una cosa que aprendí por las malas: un diagrama generado también puede mentir si lo generas sobre código muerto.
Tenía clases que ya nadie usaba, pero seguían en el repositorio. El diagrama las pintaba tan orgulloso, con sus flechas, como si importaran. La herramienta no distingue lo vivo de lo zombi. Solo lee lo que hay.
Así que la generación automática no te salva de tener el código limpio. Al revés, la exige. Un diagrama generado es tan honesto como honesto sea tu repositorio. Si guardas basura, la basura sale dibujada.
Esto, curiosamente, se convirtió en una herramienta de limpieza. Cuando veo en el diagrama una caja que no tiene sentido, voy y borro el código muerto. El diagrama me delata mi propia dejadez.
Foto: illustration of smartphone application screenshots por Hal Gatewood en Unsplash.
¿Quieres más?
Recibe los nuevos artículos sobre gatos, escritura y código. Sin frecuencia fija, sin paja de IA, sin spam.
Suscribirme