In fiecare proiect de software development exista un moment in care trebuie sa lucram la dezvoltarea unei diagrame de arhitectura. Indiferent ca folosim un model formal (ex Kruchten 4+1, Rozanski & Woods etc) sau nu, exista o nevoie de a documenta anumite componente ale aplicatiei prin dezvoltarea de diagrame.

In arhitectura software, aceste diagrame sunt construite in concordanta cu un set de reguli care tin de un anumit model, dar pentru acest articol prefer sa raman doar la idea de diagrama de arhitectura si sa nu devin foarte formal; nu planuiesc sa mai acopar si alte aspecte.

Din experienta mea ca arhitect software si trainer pe acest subiect sunt foarte multe discrepante in cadrul proiectelor, in cadrul echipelor din proiect si intre programatori privind la modul in care ar trebui dezvoltate aceste diagrame. Am vazut nenumarate provocari legate de inconsistenta, fragmentare si granularitate in ceea ce priveste informatia care ar trebui introdusa si modul in care ar trebui sa arate diagramele. In comparatie cu un model arhitectural care trebuie sa fie formal si standardizat, diagramele nu trebuie sa fie formalizate sau sa urmeze un anumit standard.

Cu toate acestea diagramele trebuie sa fie descriptive, consistente, precise si bazate pe cod. De aceea este important ca orice arhitect sau inginer software sa aiba in vedere cateva criterii pentru dezvoltarea de diagrame, deoarece constituie elementul comun prin care se comunica arhitectura aplicatiei de-alungul timpului (eg, structura, elemente, relatii, proprietati, principii) si intre diferitele parti – sau stakeholderi - implicate in proiect (fiecare avand un anumit background tehnic si un anumit set de interese).

Provocari in dezvoltarea de diagrame arhitecturale

Inainte de a discuta fiecare din aceste provocari in parte, as vrea sa va aduc in atentie o veche zicala britanica “o poza face cat o mie de cuvinte”. Conform explicatiei de pe wikipedia acest lucru se refera la notiunea conform careia o idee complexa poate sa fie comunicata printr-o simpla imagine sau ca imaginea unui lucru functioneaza mai bine in a transmite esenta acestuia in comparative cu o descriere. Acelasi concept se aplica si la diagrame: daca genereaza mai multe intrebari decat raspunsuri ofera, atunci diagrama nu este sufficient de precisa si elocventa.

Exemplu de diagrama gresita. Sufera de majoritaea problemelor discutate mai jos.

Ce denota fiecare forma?

• Utilizarea oricarui tip de forma care nu este documentata potrivit poate sa duca la multiple interpretari. Poate sa fie asociata de cei care o vad cu un bloc de date, cod sau proces. O simpla forma de patrat intr-o diagrama poate sa genereze nenumarate intrebari si este important sa le evitam adaugand in mod explicit detalii despre ce inseamna forma respectiva sau avand o legenda a diagramei.
  

Ce reprezinta diferitele margini ale formei?

• Fiecare margine a formei (fie ca este punctata sau cu liniuta) poate sa fie inteleasa gresit. O anumita margine se refera o anumita componenta (ex: linia punctata se refera la un container, un microservice, un layer etc.) sau tine doar de preferinta designer-ului legat de cum ar trebui sa arate? Aceste confuzii pot sa fie evitate oferind detalii clare in legenda diagramei atunci cand alegem diferite tipuri de margini.
  

Ce insemna o anumita linie sau sageata?

• O linie sau o sageata poate sa fie interpretata fie ca un flux de date (modul in care datele circula de la sistemul A la sistemul B) sau ca o relatie intre diferite elemente (componenta A depinde de componenta B). In cele mai multe cazuri relatiile intre fluxurile de date reprezentate prin sageti nu converg in aceleasi directii si este important sa notam asta in legenda diagramei.
  

Ce tip de comunicare / asociere este reprezentata de o linie sau sageata?

• Chiar daca linia se refera la un flux de date sau la o relatie intre componente, tipul de comunicare (in cazul unui flux de date) sau tipul de asociere (in cazul unei relatii intre componente) simbolizat prin intermediul unei linii sau sageti trebuie detaliat. Spre exemplu, daca linia reprezinta un flux de date, comunicarea poate sa fie sincrona sau asincrona, dar daca linia se refera la o relatie s-ar putea sa fie reprezentata prin dependenta, mostenire, implementare etc. Toate aceste detalii trebuie sa apara in legenda.
  

Ce inseamna culoarea?

• O diagrama multicolora (culori multiple pentru forme, linii) fara sa fie documentata poate sa cauzeze multe provocari (De ce sunt anumite forme verzi si altele rosii? De ce sunt anumite linii negre si altele albastre?). Schema de culori este mai putin importanta intr-o diagrama si folosirea unui numar mare de culori nu aduce plus valoare in termeni de continut sau informatii valoroase. O diagrama poate sa fie suficienta si bine proiectata folosind doar negru, cu exceptia cazurilor in care exista anumite constrangeri legate de evidentierea unor zone din digrama folosind culori. Oricum cel mai bine este sa ne concentram pe simplitate in ceea ce priveste culorile folosite, dar daca nu se poate este important sa detaliem alegerile facute.
  

Lipsa unor relatii intre elementele diagramei si entitatile izolate

• Lipsa unor relatii intre elemente sau entitati izolate intr-o diagrama pot sa fie o dovada a faptului ca aceasta nu este completa. Atat din punct de vedere structural cat si comportamental, fiecare element sau entitate ar trebui sa depinda de / sa aiba o relatie cu o alta parte a sistemului reprezentata de un alt element (aceasta relatie fiind reprezentata cu o linie sau sageata).

Acronime care induc in eroare ori sunt nedocumentate sau termeni prea vagi ori generici

• Atunci cand folosim o eticheta pentru un element din diagrama, este recomandat sa nu folosim un acronim care ar putea sa induca o alta persoana in eroare sau care sa nu fie documentat. O simpla secventa de litere (TFH, RBPM) nu inseamna nimic fara o explicatie clara a elementului pe diagrama sau, si mai bine, in legenda (ex: TFH – ticket feed handler, RBPM – rates business process manager).
• O alta caracteristica legata de denumirea elementelor din diagrama tine de termeni care sunt prea vagi sau generici (ex business logic, integration logic) care nu aduc multe informatii valoroase deoarece numele lor nu sunt indeajuns de descriptive. Acest lucru se poate intampla si la nivel de cod si sfatul meu este sa folositi de fiecare data denumiri cat mai sugestive si auto-explicative urmand principiile de clean code.

Adaugarea in diagrame a tehnologiilor, framework-urilor, limbajelor de programare sau de scripting, IDE-ul folosit sau metodologia de dezvoltare

• Designul de arhitectura software nu este legat sau bazat in mod fundamental pe o anumita tehnologie, framework, limbaj de programare sau de scripting, IDE sau metodologie de dezvoltare. Toate aceste aspecte apar mai tarziu in cadrul procesului pentru a ajuta la construirea arhitecturii, dar nu sunt punctul central. Ele nu ar trebui incluse in diagrame, ci in documentul architectural impreuna cu motivul pentru care le-am ales.
  

Amestecarea elementelor statice si de runtime in aceeasi diagrama

• Elementele de runtime (threads, procese, masini virtuale, containere, servicii, firrewalls, data repositories etc) nu apar la compile time si este recomandat sa evitam amestecarea aceste elemente cu cele statice (componente, pachete, clase) in aceeasi diagrama. Exista diagrame dedicate (concurrency diagram, deployment diagram) care se concentreaza pe elementele de runtime si este important sa facem o distinctie intre aceste doua categorii de elemente si sa evitam amestecarea lor.

Introducerea de afirmatii precum “Voi descrie verbal asta” sau “Voi explica acest aspect mai tarziu”

• Orice lucru care nu este explicat in cadrul diagramei este considerat ca fiind un element lipsa si nu exista loc pentru detalii verbale care sa completeze diagrama. De ce? Deoarece toate explicatiile orale care sunt mentionate dar nu sunt incluse in diagrama se pierd, si mai tarziu, atunci cand alte persoane implicate in proiect (programatori, arhitecti) vor citi diagrama, ei nu vor stii ca aceste explicatii exista. Incercati sa includeti toate detaliile necesare intr-o diagrama pentru a evita orice explicatii viitoare.
  

Nivele de detaliere diferite care intra in conflict, inclusiv abstractiile mixte

• Adaugarea unor elemente care tin de diferite nivele de abstractie in cadrul aceleiasi diagrame ar putea sa intre in conflict, din moment ce sunt vazute din perspective diferite. Spre exemplu adaugarea unor componente intr-o diagrama de tip context architectural sau clase intr-o diagrama de tip deployment ar putea sa schimbe scopul pentru care a fost dezvoltata. Atunci cand lucrati la o diagrama incercati sa pastrati acelasi nivel de abstractie.
  

Diagrame care sunt prea vagi, insuficiente sau care contin un nivel prea mare de detaliere

• “Everything should be made as simple as possible, but not simpler.” este un citat bine cunoscut care apartine lui Albert Einstein. Acelasi lucru este valid si pentru diagrame; nivelul si granularitatea informatiei din diagrama ar trebui stabilit cu cat mai multa grija. Acest lucru nu este usor; depinde de modelul arhitectural folosit, experienta arhitectului software si complexitatea sistemului. 
  

In cea de-a doua parte a articolului vom discuta despre criteriile pe care sa le avem in vedere pentru a dezvolta diagrama de arhitectura eficienta si cum putem sa le mentinem actualizate.

Vrei sa iti imbunatatesti abilitatile de arhitectura software?
Inscrie-te la cursul nostru de Arhitectura software - Metodologie si Concepte

Ionut Balosin
Software Architect