The Art of Crafting Architectural Diagrams

Ad un certo punto, in ogni progetto software in cui siamo coinvolti, potrebbe esserci la necessità di creare diagrammi architetturali. Sia che stiamo seguendo un modello architettonico formale (ad esempio Kruchten 4+1, Rozanski & Woods, ecc) o no, c’è la necessità di documentare alcune parti dell’applicazione creando diagrammi. Nell’architettura del software, tali diagrammi sono creati in conformità con le viste che sono relative ad un punto di vista specifico che potrebbe essere parte di un modello, ma nell’articolo attuale preferisco attenermi al termine diagramma architettonico e non essere molto formale; tutti gli altri aspetti non sono destinati ad essere trattati qui.

In base alla mia esperienza come architetto del software e formatore tecnico, ci sono un sacco di discrepanze tra i progetti e all’interno del team di progetto da sviluppatore a sviluppatore nel modo in cui vengono creati i diagrammi architetturali. Ho visto molti problemi riguardanti l’incoerenza, la frammentazione e la granularità delle informazioni rese e l’aspetto dei diagrammi. Rispetto a un modello architettonico che deve essere formale e standardizzato, i diagrammi potrebbero non essere necessariamente formalizzati o seguire uno standard specifico.

Nonostante, i diagrammi devono essere auto-descrittivi, coerenti, abbastanza accurati e collegati al codice. Ecco perché è importante che ogni architetto o ingegnere del software si basi su diverse linee guida quando crea i diagrammi architettonici, dal momento che sono il terreno comune per comunicare l’architettura dell’applicazione nel tempo (ad esempio struttura, elementi, relazioni, proprietà, principi) e tra diversi stakeholder che hanno vari background tecnici e preoccupazioni.

I trabocchetti attuali nella progettazione dei diagrammi architettonici

Prima di approfondire i possibili problemi, mi piacerebbe avere un’analogia con un idioma inglese che dice “un’immagine vale più di mille parole”. Come da questa spiegazione su wiki, “si riferisce alla nozione che un’idea complessa può essere trasmessa con una sola immagine fissa o che un’immagine di un soggetto trasmette il suo significato o la sua essenza più efficacemente di quanto faccia una descrizione”. Lo stesso concetto vale per un diagramma architettonico: se solleva più domande che risposte, il diagramma non è ben creato. Non lasciare che un diagramma architettonico richieda migliaia di parole o chiarimenti!

Esempio di un diagramma architettonico improprio. Soffre della maggior parte dei problemi descritti di seguito

Esaminiamo ora una lista di trabocchetti che potrebbero ostacolare il processo di creazione corretta di diagrammi architettonici.

Cosa denota una scatola o una forma?

• L’uso di qualsiasi tipo di scatola o forma che non è adeguatamente documentata potrebbe causare molteplici interpretazioni. Potrebbe essere associato a un pezzo di dati, a un mucchio di codice o a un processo. Solo una semplice casella in un diagramma potrebbe sollevare molteplici dubbi ed è molto importante evitarli aggiungendo esplicitamente dettagli sul significato della casella o della forma nella legenda del diagramma.

Cosa rappresentano i diversi bordi di una forma?

• Ogni bordo di una forma (ad esempio tratteggiato, punteggiato, ecc.) può essere frainteso nel caso di un diagramma povero. Un bordo specifico si riferisce a un tipo di componente specifico (ad esempio una linea tratteggiata si riferisce a un contenitore, un microservizio, un livello, ecc.), o è solo la preferenza del designer per avere un look and feel ricco? Evitare tale confusione fornendo dettagli accurati nel diagramma di legenda quando si scelgono bordi multipli o non standard.

Cosa denotano una linea o una freccia?

• Una linea o una freccia può essere interpretata sia come un flusso di dati (es. i dati fluiscono dal sistema A al sistema B) o come una relazione tra elementi (es. il componente A dipende dal componente B). Nella maggior parte dei casi le relazioni o i flussi di dati rappresentati dalle frecce non convergono nelle stesse direzioni ed è importante scriverlo esplicitamente nella legenda del diagramma.

Qual è il tipo di comunicazione/associazione indicato da una linea o da una freccia?

• Anche se la linea si riferisce a un flusso di dati o a una relazione tra componenti, il tipo di comunicazione (es. in caso di flusso di dati) o il tipo di associazione (es. in caso di relazione) denotato da quella linea o freccia deve essere specificato. Per esempio, se la linea rappresenta un flusso di dati, la comunicazione potrebbe essere sincrona o asincrona, ma se la linea si riferisce a una relazione, potrebbe essere rappresentata da una dipendenza, eredità, implementazione, ecc. Tutti questi dettagli devono essere presenti nella legenda del diagramma.

Che cosa significa quel colore?

• Avere un diagramma policolore ‘perrot’ (es. più colori per le caselle, le linee) senza un’adeguata intenzione documentata potrebbe sollevare molteplici domande (es. perché alcune caselle sono verdi e altre rosse? Perché alcune linee sono nere e altre blu?) Lo schema dei colori è meno importante in un diagramma, e l’uso di un ricco numero di colori non porta troppo contenuto aggiuntivo o informazioni di valore. Un diagramma potrebbe anche essere auto esplicativo e ben disegnato solo usando colori bianchi e neri, a meno che non ci sia un vincolo stringente per enfatizzare alcune parti del diagramma usando colori distinguibili. In ogni caso, è sempre meglio attenersi alla semplicità in termini di colori usati, ma se non è il caso, non dimenticare di dettagliare la scelta.

Mancanza di relazioni tra elementi del diagramma o entità isolate

• La mancanza di relazioni tra elementi o entità isolate in un diagramma potrebbe essere un indizio di incompletezza. Sia da una prospettiva strutturale che comportamentale, ogni elemento o entità dovrebbe dipendere da / avere una relazione (rappresentata da una linea o una freccia) con un’altra parte del sistema rappresentata da un elemento diverso.

Acronimi fuorvianti/ non documentati o termini troppo vaghi/generici

• Quando si usa un’etichetta per un elemento in un diagramma, si raccomanda di non usare nessun acronimo fuorviante o non documentato che possa causare confusioni. Solo una sequenza di lettere (es. TFH, RBPM) non significa nulla senza una spiegazione adeguata sull’elemento del diagramma o, ancora meglio, nella legenda del diagramma (es. TFH – ticket feed handler, RBPM – rates business process manager).

• Un’altra caratteristica della denominazione degli elementi del diagramma riguarda i termini estremamente vaghi o generici (es. business logic, integration logic) che non portano troppe informazioni di valore perché i loro nomi non sono propriamente auto-descrittivi. Questo problema potrebbe risiedere anche a livello di codice, e il suggerimento sarebbe di usare sempre nomi autoesplicativi e suggestivi seguendo i principi del codice pulito.

Evidenzia tecnologie, framework, linguaggi di programmazione o di scripting, IDE o metodologia di sviluppo sui diagrammi

• La progettazione architettonica non è collegata o fondamentalmente basata su nessuna tecnologia, framework, linguaggio di programmazione o di scripting, IDE o metodologia di sviluppo. Tutti questi vengono dopo nel processo per aiutare a costruire l’architettura, ma non sono il punto centrale. Non dovrebbero essere inclusi nei diagrammi, ma dichiarati nella descrizione dell’architettura, includendo la logica della loro scelta.

Mischia elementi runtime e statici nello stesso diagramma

• Gli elementi runtime (ad esempio thread, processi, macchine virtuali, contenitori, servizi, firewall, repository di dati, ecc) non sono presenti in fase di compilazione e si raccomanda di evitare di mischiare questi elementi con quelli statici (ad esempio componenti, pacchetti, classi) nello stesso diagramma. Ci sono tipi di diagrammi dedicati (ad esempio diagramma di concorrenza, diagramma di distribuzione) che sono principalmente focalizzati sugli elementi di runtime ed è importante distinguere tra queste due categorie di elementi ed evitare di mischiarli il più possibile.

Fare supposizioni come “descriverò verbalmente questo”, e “lo spiegherò più tardi”

• Tutto ciò che non è descritto dal diagramma stesso manca, e non c’è spazio per fornire dettagli verbali per completare un diagramma. Perché? Perché tutte le spiegazioni menzionate oralmente ma non catturate nel diagramma sono perse, e più tardi, quando qualche altro stakeholder (ad esempio sviluppatore, architetto) leggerà il diagramma, non sarà a conoscenza di queste spiegazioni. Cerca di includere tutti i dettagli necessari in un diagramma per evitare qualsiasi necessità di ulteriori chiarimenti.

Livelli di dettaglio contrastanti o astrazioni miste

• L’aggiunta di elementi relativi a diversi livelli di astrazione nello stesso diagramma potrebbe entrare in conflitto, poiché sono visti da prospettive diverse. Per esempio, aggiungere componenti ad un diagramma di contesto architettonico o classi ad un diagramma di dispiegamento potrebbe divergere lo scopo del diagramma stesso. Quando si crea un diagramma, cercare di attenersi allo stesso livello di astrazione.

Diagrammi confusi o troppo vaghi che cercano di mostrare un livello di dettaglio eccessivo o insufficiente

• “Tutto dovrebbe essere reso il più semplice possibile, ma non più semplice” è una nota citazione di Albert Einstein. Questo è valido anche per i diagrammi architettonici; il livello e la granularità delle informazioni catturate dovrebbero essere eletti in modo significativo. Questa non è una cosa facile; dipende dal modello architettonico usato, dall’esperienza dell’architetto e dalla complessità del sistema.

Linee guida da seguire quando si creano diagrammi architettonici

Oltre alle insidie di cui sopra, che devono far parte di una lista di controllo preliminare per evitarle, ci sono anche linee guida generali su come creare correttamente i diagrammi:

Scegliere il numero ottimale di diagrammi

• Come disse Philippe Kruchten, “l’architettura è una bestia complessa. Usare un solo diagramma per rappresentare l’architettura si traduce in un pasticcio semantico incomprensibile”. Per documentare i sistemi moderni non si può finire con un solo tipo di diagramma, ma quando si creano diagrammi architettonici non è sempre immediato quali diagrammi scegliere e quanti crearne. Ci sono molteplici fattori da prendere in considerazione prima di prendere una decisione; per esempio, la natura e la complessità dell’architettura, le competenze e l’esperienza dell’architetto del software, il tempo disponibile, la quantità di lavoro necessario per mantenerli, e ciò che ha senso o è utile per soddisfare le preoccupazioni degli stakeholder. Per esempio, un ingegnere di rete probabilmente vorrà vedere un modello di rete esplicito che includa host, porte di comunicazione e protocolli; un amministratore di database è preoccupato di come il sistema manipola, gestisce e distribuisce i dati, ecc. Sulla base di tutti questi aspetti, si raccomanda di scegliere il numero ottimale di diagrammi, qualunque esso sia.
• Se i diagrammi sono insufficienti (es. sotto-documentazione), parti dell’architettura potrebbero essere nascoste o non documentate; d’altra parte, se sono troppi (es. sovra-documentazione), lo sforzo necessario per mantenerli coerenti, aggiornati e non frammentati potrebbe aumentare considerevolmente.

Mantenere la coerenza strutturale e semantica tra i diagrammi

• Ogni diagramma dovrebbe essere coerente con gli altri in termini di caselle, forme, bordi, linee, colori, ecc. L’aspetto strutturale dovrebbe essere lo stesso e ogni stakeholder non dovrebbe avere difficoltà a capire i diagrammi creati da diversi sviluppatori all’interno di un team. Idealmente, attenersi ad uno strumento di diagrammi comune e riutilizzarlo in tutti i progetti.
• Dal punto di vista semantico, tutti questi diagrammi dovrebbero essere periodicamente sincronizzati alle ultime modifiche al codice e tra di loro, poiché un cambiamento in un diagramma potrebbe avere un impatto sugli altri. Questo processo potrebbe essere attivato manualmente o automaticamente utilizzando uno strumento di modellazione. Quest’ultimo è il meccanismo preferito, ma questo dipende da progetto a progetto, in tutti i casi l’idea è di mantenere la coerenza tra i diagrammi e il codice, indipendentemente dal metodo o dallo strumento. Simon Brown ha detto “i diagrammi non sono utili per il miglioramento dell’architettura se non sono collegati al codice”, il che sottolinea l’idea della coerenza semantica.

Evitare la frammentazione dei diagrammi

• Avere più diagrammi potrebbe rendere la descrizione architettonica difficile da capire ma anche uno sforzo significativo nel mantenerli. Come effetto collaterale, potrebbe apparire la frammentazione (ad esempio due o più diagrammi illustrano lo stesso attributo di qualità – prestazioni, scalabilità, ecc. – ma ognuno di essi è individualmente incompleto). In questi casi si raccomanda di rimuovere i diagrammi che non riflettono gli attributi di qualità rilevanti (legati a requisiti architettonicamente significativi) o, ancora meglio, di unire i diagrammi (per esempio, concurrency e deployment).

Mantenere la tracciabilità tra i diagrammi

• E’ anche importante essere in grado di controllare la storia, fare confronti tra diverse versioni del diagramma e tornare facilmente a una versione precedente. Usare uno strumento di modellazione che non lo permette potrebbe essere un impedimento. Le ultime tendenze del settore si basano sull’uso di un linguaggio di testo semplice e intuitivo per generare i diagrammi, il che sembra risolvere il problema della tracciabilità. Un altro vantaggio di tale approccio è che assicura implicitamente una coerenza strutturale omogenea tra i diagrammi.

Aggiungi leggende accanto ai diagrammi architettonici

• Se non segui un linguaggio standard di descrizione architettonica (es. UML, ArchiMate), dettaglia ogni pezzo del diagramma nella legenda (es. caselle, forme, bordi, linee, colori, acronimi, ecc).
• Se questo non è il caso, nella legenda basta aggiungere il linguaggio di descrizione architettonica come chiave e non c’è bisogno di ulteriori spiegazioni, poiché ogni lettore seguirà le specifiche del linguaggio per capire il diagramma.

Il linguaggio di descrizione architettonica (ad esempio UML, ArchiMate, ecc.) fa la differenza?

Ci sono molte opinioni su quale sia il giusto linguaggio di descrizione da adottare nel progetto. Alcune persone potrebbero sostenere che UML è rigido e non abbastanza flessibile per modellare il progetto architettonico, un punto di vista con cui sono d’accordo. Tuttavia, in alcuni casi potrebbe essere più che sufficiente per documentare i fondamenti di un’architettura senza fare affidamento su qualsiasi caratteristica di estensibilità UML come profili e stereotipi. Dando un’occhiata ad altri linguaggi di descrizione, possiamo vedere che ArchiMate è più potente e adatto alla modellazione di sistemi aziendali rispetto a UML; c’è anche BPMN che è particolarmente mirato ai processi aziendali, ecc. I paragoni potrebbero continuare, ma non intendo fare una revisione approfondita, dato che non è l’obiettivo di questo articolo.

Avere un linguaggio di descrizione architettonica abbastanza completo e flessibile è un grande passo avanti e questo dovrebbe essere un criterio solido quando lo si sceglie. Ma dal mio punto di vista, la vera causa risiede altrove ed è legata al fatto che la documentazione architettonica non viene creata affatto. La gente spesso trova la creazione noiosa, inutile o senza senso. Il numero di progetti software senza, o con documentazione impropria, è enorme. Non credo che le persone stiano intensamente creando o siano coinvolte nella creazione di diagrammi architettonici utilizzando un linguaggio di descrizione improprio, e se dovessero sostituirlo con uno migliore i risultati sarebbero molto diversi. No, le persone non stanno creando alcuna documentazione architettonica (inclusi i diagrammi architettonici), e ancora peggio, la maggior parte di loro non ha idea di come crearla correttamente. Queste sono le cose che dobbiamo affrontare prima – capire perché la documentazione è importante e come crearla correttamente (formando gli ingegneri del software); poi la selezione di strumenti adeguati viene naturale.

Come si possono mantenere aggiornati i diagrammi mentre il sistema viene sviluppato, e i cambiamenti all’architettura si materializzano

Ci sono pochi approcci per mantenere aggiornati i diagrammi; di seguito ne esprimo tre. La prima opzione, e la più semplice, sarebbe quella di generare automaticamente i diagrammi dal codice sorgente, che è la verità di base. Questo garantisce che siano tutti coerenti con il codice. Sfortunatamente, con gli strumenti esistenti questo non è ancora pienamente possibile (almeno a mia conoscenza), poiché gli strumenti attuali non possono creare alcun tipo di diagramma accurato e significativo solo sulla base del codice sorgente, senza un significativo intervento manuale. Len Bass ha detto “l’ambiente di sviluppo ideale è uno per il quale la documentazione è disponibile essenzialmente gratis con la pressione di un pulsante”, implicitamente auto generando i diagrammi, ma non abbiamo raggiunto quel punto.

Il secondo approccio sarebbe quello di progettare prima i diagrammi usando uno strumento dedicato che poi genera gli scheletri del codice sorgente (ad esempio componenti/pacchetti con confini, API) usati successivamente dagli sviluppatori per riempire il codice. In questo modo, ogni cambiamento nell’architettura deve essere innescato dal diagramma stesso che automaticamente potrebbe rigenerare o aggiornare lo scheletro del codice.

L’ultimo caso comporta l’aggiornamento manuale dei diagrammi ogni volta che una nuova caratteristica – che ha un impatto sul disegno architettonico – viene implementata. Per essere sicuri che tutte le modifiche al codice si riflettano nei diagrammi, si raccomanda che l’aggiornamento dei diagrammi sia parte della definizione di fatto nel processo di sviluppo. Questo scenario è meno raccomandato perché potrebbe facilmente causare diagrammi obsoleti o incoerenti (ad esempio gli sviluppatori spesso dimenticano o non sono in vena di aggiornare i diagrammi) e purtroppo questo accade ancora nella maggior parte dei progetti.

Tenendo conto degli strumenti esistenti, la mia raccomandazione è di avere un mix; per mescolare automaticamente e manualmente creare diagrammi. Per esempio, cercare di generare automaticamente diagrammi, che possono essere ragionevolmente resi da strumenti basati sul codice sorgente senza troppo rumore (ad esempio, informazioni troppo ingombranti o senza senso). In questa categoria possiamo includere sia diagrammi con un alto grado di volatilità (ad esempio più inclini a frequenti cambiamenti di sviluppo, di solito con un’astrazione inferiore) o, al contrario, diagrammi statici. Alcuni di questi diagrammi potrebbero riferirsi a diagrammi di contesto, diagrammi di architettura di riferimento, diagrammi di pacchetto, diagrammi di classe, diagrammi di entità, ecc. Tuttavia, in alcuni casi, non è ovvio basandosi solo sul codice sorgente come il sistema soddisfi alcuni attributi di qualità (ad esempio disponibilità, scalabilità, prestazioni), quindi la creazione automatica di diagrammi non è un’opzione sufficiente. Deve essere integrata da diagrammi modellati manualmente. Alcuni esempi di tali diagrammi includono diagrammi di sequenza, diagrammi di stato, diagrammi di concorrenza, diagrammi di distribuzione, diagrammi operativi, ecc.

Quali complicazioni (o semplificazioni) emergono per i diagrammi architettonici quando si tratta di architetture moderne (ad es.Ad esempio i microservizi?

I microservizi o qualsiasi altro stile architettonico moderno (ad esempio serverless, event driven) guidano solo la struttura del sistema, come i componenti comunicano tra loro (ad esempio le relazioni tra loro) e quali principi li governano. Personalmente, non penso che lo stile architettonico dovrebbe cambiare la logica o i concetti intorno alla creazione dei diagrammi (e implicitamente la descrizione architettonica), né ciò che essi dovrebbero catturare. Tuttavia, quando si parla di architetture di sistemi moderni, che di solito hanno livelli più alti di complessità rispetto ai sistemi vecchi e classici (ad esempio monoliti), hanno sicuramente un impatto sulla descrizione architetturale e implicitamente sui diagrammi, nel senso che ci sono molteplici considerazioni di cui occuparsi. Tali considerazioni potrebbero riguardare la comprensione del numero di componenti distribuiti (ad esempio micro-servizi distribuiti), il tipo di ogni componente, come i componenti comunicano tra loro (ad esempio confini, API, messaggi), il loro ciclo di vita e chi possiede ogni componente.

Tenendo conto di tutto ciò, le viste che catturano la decomposizione del sistema, lo sviluppo, il deployment e l’operabilità dovrebbero essere considerate per default. Immaginate un sistema con un numero impressionante di microservizi, per esempio; in questo caso il numero di diagrammi potrebbe aumentare significativamente perché ogni microservizio potrebbe finire per avere il proprio set di diagrammi. Problemi di coerenza (ad esempio, cambiare l’API di un servizio ha un impatto su altri servizi X, quindi tutti i diagrammi interessati devono essere aggiornati), frammentazione (ad esempio, l’alta disponibilità o le prestazioni tra servizi distribuiti non sono consolidate in un diagramma) o problemi trasversali (ad esempio, chi è incaricato di illustrare, in modo consolidato, aspetti come il monitoraggio o la sicurezza su interi elementi del sistema) potrebbero non essere facilmente gestiti. Oltre a questo ci potrebbero essere sfide relative alla coesistenza e alla collaborazione dei team durante lo sviluppo del progetto, e anche dopo, per mantenerlo.

Per riassumere, i sistemi moderni con architetture complesse potrebbero portare ulteriori preoccupazioni che potrebbero portare a complicazioni anche a livello di diagrammi.

Informazioni sull’autore

Ionut Balosin è un architetto di software e formatore tecnico indipendente. È un oratore regolare alle conferenze sullo sviluppo del software e ai meetup in tutto il mondo, tenendo presentazioni, corsi di formazione e workshop. Per maggiori dettagli controlla il suo sito web.