Umění tvorby architektonických diagramů

V určitém okamžiku může v každém softwarovém projektu, na kterém se podílíme, vzniknout potřeba vytvořit architektonické diagramy. Ať už se řídíme formálním architektonickým modelem (např. Kruchten 4+1, Rozanski & Woods atd.), nebo ne, vzniká potřeba dokumentovat některé části aplikace vytvořením diagramů. V softwarové architektuře se takové diagramy vytvářejí v souladu s pohledy, které se vztahují k určitému hledisku, které by mohlo být součástí modelu, ale v tomto článku se raději budu držet termínu architektonický diagram a nebudu příliš formální; všechny ostatní aspekty zde nemají být zahrnuty.

Na základě mých zkušeností softwarového architekta a technického školitele existuje mnoho rozdílů mezi projekty a uvnitř projektového týmu od vývojáře k vývojáři ve způsobu vytváření architektonických diagramů. Viděl jsem mnoho problémů týkajících se nekonzistence, roztříštěnosti a granularity vykreslovaných informací a vzhledu diagramů. Ve srovnání s architektonickým modelem, který musí být formalizovaný a standardizovaný, nemusí být diagramy nutně formalizované nebo se řídit určitým standardem.

Diagramy nicméně musí být samy o sobě popisné, konzistentní, dostatečně přesné a propojené s kódem. Proto je důležité, aby se každý architekt nebo softwarový inženýr při tvorbě architektonických diagramů opíral o několik pokynů, protože jsou společným základem pro komunikaci architektury aplikace v průběhu času (např. struktura, prvky, vztahy, vlastnosti, principy) a mezi různými zúčastněnými stranami, které mají různé technické zázemí a zájmy.

Současná úskalí při navrhování architektonických diagramů

Než se pustíme hlouběji do možných problémů, rád bych měl analogii k anglickému idiomu, který říká „obrázek vydá za tisíc slov“. Podle tohoto vysvětlení na wiki „odkazuje na představu, že složitou myšlenku lze vyjádřit pouze jediným statickým obrázkem nebo že obrázek předmětu vyjadřuje jeho význam nebo podstatu účinněji než popis“. Stejný koncept platí i pro architektonický diagram: pokud vyvolává více otázek než odpovědí, není diagram dobře vytvořen. Ať architektonický diagram nevyžaduje tisíce slov nebo vysvětlení!“

Příklad nevhodně vytvořeného architektonického diagramu. Trpí většinou níže popsaných problémů

Projděme si nyní opakovaně seznam úskalí, která mohou bránit procesu správné tvorby architektonických diagramů.

Co označuje rámeček nebo tvar?

• Použití jakéhokoli druhu rámečku nebo tvaru, který není řádně zdokumentován, může způsobit mnohočetné interpretace. Může být spojen buď s částí dat, svazkem kódu, nebo procesem. I pouhý rámeček v diagramu může vyvolat více pochybností a je velmi důležité se jim vyhnout tím, že do legendy diagramu výslovně doplníte podrobnosti o významu rámečku nebo tvaru.

Co představují různé hrany tvaru?

• Každá hrana tvaru (např. čárkovaná, tečkovaná atd.) může být v případě špatného diagramu špatně pochopena. Odkazuje určitý okraj na konkrétní typ komponenty (např. přerušovaná čára odkazuje na kontejner, mikroslužbu, vrstvu atd.), nebo jde jen o preferenci návrháře, který chce mít bohatý vzhled? Vyhněte se takovým zmatkům tím, že při volbě vícenásobných nebo nestandardních okrajů uvedete v legendě diagramu přesné údaje.

Co označuje čára nebo šipka?

• Čáru nebo šipku lze interpretovat buď jako tok dat (např. data proudí ze systému A do systému B), nebo jako vztah mezi prvky (např. komponenta A závisí na komponentě B). Ve většině případů se vztahy nebo datové toky znázorněné šipkami nesbíhají ve stejných směrech a je důležité to výslovně zapsat do legendy diagramu.

Jaký je typ komunikace/asociace označené čárou nebo šipkou?

• I když čára označuje datový tok nebo vztah mezi prvky, musí být typ komunikace (např. v případě datového toku) nebo typ asociace (např. v případě vztahu) označený touto čárou nebo šipkou podrobně popsán. Například pokud řádek představuje tok dat, může být komunikace synchronní nebo asynchronní, ale pokud řádek odkazuje na vztah, může být reprezentován závislostí, dědičností, implementací atd. Všechny tyto podrobnosti musí být přítomny v legendě diagramu.

Co znamená tahle barva?“

• Mít „perrot“ policolor diagram (např. více barev pro políčka, čáry) bez náležitě zdokumentovaného záměru může vyvolat řadu otázek (např. proč jsou některá políčka zelená a jiná červená? Proč jsou některé čáry černé a jiné modré?“). Barevné schéma je v diagramu méně důležité a použití bohatého počtu barev nepřináší příliš mnoho dalšího obsahu nebo cenných informací. Diagram by také mohl být samovysvětlující a dobře navržený jen s použitím černé a bílé barvy, pokud neexistuje přísné omezení zdůraznit některé části diagramu použitím rozlišitelných barev. V každém případě je vždy lepší držet se jednoduchosti, pokud jde o použité barvy, ale pokud tomu tak není, nezapomeňte volbu podrobně popsat.

Chybějící vztahy mezi prvky diagramu nebo izolovanými entitami

• Chybějící vztahy mezi prvky nebo izolovanými entitami v diagramu mohou být vodítkem neúplnosti. Ze strukturálního i behaviorálního hlediska by měl každý prvek nebo entita záviset / mít vztah (reprezentovaný čárou nebo šipkou) s jinou částí systému reprezentovanou jiným prvkem.

Chybějící zavádějící/nedokumentované zkratky nebo příliš vágní/obecné termíny

• Při použití označení prvku v diagramu se doporučuje nepoužívat zavádějící nebo nedokumentované zkratky, které by mohly způsobit zmatky. Pouhá posloupnost písmen (např. TFH, RBPM) bez náležitého vysvětlení na prvku diagramu nebo ještě lépe v legendě diagramu nic neznamená (např. TFH – ticket feed handler, RBPM – rates business process manager).

• Další charakteristika pojmenování prvků diagramu se týká extrémně vágních nebo obecných termínů (např. business logic, integration logic), které nepřinášejí příliš mnoho cenných informací, protože jejich názvy nejsou náležitě sebepopisné. Tento problém se může vyskytovat i na úrovni kódu, a proto bychom navrhovali vždy používat samovysvětlující a sugestivní názvy podle zásad čistého kódu.

Zdůrazňovat na diagramech technologie, rámce, programovací nebo skriptovací jazyky, IDE nebo metodiku vývoje

• Architektonický návrh nesouvisí ani není zásadně založen na žádné technologii, rámci, programovacím nebo skriptovacím jazyce, IDE nebo metodice vývoje. Všechny tyto prvky přicházejí později v procesu, aby pomohly vytvořit architekturu, ale nejsou ústředním bodem. Neměly by být zahrnuty do diagramů, ale měly by být uvedeny v popisu architektury včetně zdůvodnění jejich výběru.

Míchání runtime a statických prvků ve stejném diagramu

• Runtime prvky (např. vlákna, procesy, virtuální stroje, kontejnery, služby, firewally, úložiště dat atd.) nejsou přítomny v době kompilace a doporučuje se vyhnout se míchání těchto prvků se statickými (např. komponenty, balíčky, třídy) ve stejném diagramu. Existují specializované typy diagramů (např. diagram souběhu, diagram nasazení), které jsou primárně zaměřeny na prvky v době běhu, a je důležité tyto dvě kategorie prvků rozlišovat a co nejvíce se vyhýbat jejich míchání.

Vycházejte z předpokladů typu „toto popíšu slovně“ a „vysvětlím to později“

• Všechno, co není popsáno v samotném diagramu, chybí a není zde prostor pro uvedení slovních detailů, které by diagram doplnily. Proč? Protože všechna ústně uvedená, ale v diagramu nezachycená vysvětlení se ztratí a později, až budou diagram číst některé další zúčastněné strany (např. vývojář, architekt), nebudou o těchto vysvětleních vědět. Snažte se do diagramu zahrnout všechny potřebné podrobnosti, abyste se vyhnuli potřebě dalších vysvětlení.

Konfliktní úrovně podrobností nebo smíšené abstrakce

• Přidání prvků souvisejících s různými úrovněmi abstrakce do stejného diagramu může být konfliktní, protože jsou viděny z různých perspektiv. Například přidání komponent do diagramu architektonického kontextu nebo tříd do diagramu nasazení by se mohlo rozcházet s účelem samotného diagramu. Při vytváření diagramu se snažte držet stejné úrovně abstrakce.

Přehledné nebo příliš vágní diagramy se snaží zobrazit příliš velkou nebo nedostatečnou úroveň detailů

• „Vše by mělo být co nejjednodušší, ale ne jednodušší“ je známý citát patřící Albertu Einsteinovi. To platí i pro architektonické diagramy; úroveň a granularita zachycených informací by měla být smysluplně volena. To není jednoduchá věc; záleží na použitém architektonickém modelu, zkušenostech architekta a složitosti systému.

Pokyny, kterými je třeba se řídit při tvorbě architektonických diagramů

Kromě výše uvedených úskalí, která musí být součástí předběžného kontrolního seznamu, abychom se jim vyhnuli, existují také obecné pokyny, jak správně vytvářet diagramy:

Zvolte optimální počet diagramů

• Jak řekl Philippe Kruchten, „architektura je složité zvíře. Použití jediného diagramu k reprezentaci architektury vede k nesrozumitelnému sémantickému nepořádku“. Pro dokumentaci moderních systémů nemůžeme skončit pouze u jednoho druhu diagramů, ale při vytváření architektonických diagramů není vždy jednoznačné, jaké diagramy zvolit a kolik jich vytvořit. Před rozhodnutím je třeba vzít v úvahu více faktorů; například povahu a složitost architektury, dovednosti a zkušenosti softwarového architekta, dostupný čas, množství práce potřebné k jejich údržbě a to, co má smysl nebo je užitečné pro uspokojení zájmů zúčastněných stran. Například síťový inženýr bude pravděpodobně chtít vidět explicitní model sítě včetně hostitelů, komunikačních portů a protokolů; správce databáze se zajímá o to, jak systém manipuluje s daty, jak je spravuje a distribuuje atd. Na základě všech těchto hledisek se doporučuje vybrat optimální počet diagramů, ať už je tento počet jakýkoli.
• Pokud je diagramů málo (např. nedostatečná dokumentace), mohou být části architektury skryté nebo nedokumentované; na druhou stranu, pokud jich je příliš mnoho (např. nadměrná dokumentace), může se značně zvýšit úsilí potřebné k tomu, aby byly konzistentní, aktualizované a nebyly roztříštěné.

Dodržujte strukturální a sémantickou konzistenci napříč diagramy

• Každý diagram by měl být konzistentní s ostatními, pokud jde o rámečky, tvary, ohraničení, čáry, barvy atd. Strukturální vzhled by měl být stejný a každá zúčastněná strana by neměla mít potíže s pochopením diagramů vytvořených různými vývojáři uvnitř týmu. V ideálním případě se držte společného nástroje pro tvorbu diagramů a opakovaně jej používejte ve všech projektech.
• Z hlediska sémantiky by měly být všechny tyto diagramy pravidelně synchronizovány s nejnovějšími změnami kódu a mezi sebou, protože změna v jednom diagramu může mít dopad na ostatní. Tento proces může být spuštěn ručně nebo automaticky pomocí modelovacího nástroje. Druhý jmenovaný mechanismus je preferovaný, ale záleží na jednotlivých projektech, ve všech případech jde o to, aby byla zachována konzistence mezi diagramy a kódem nezávisle na metodě nebo nástroji. Simon Brown řekl, že „diagramy nejsou užitečné pro zlepšení architektury, pokud nejsou propojeny s kódem“, což zdůrazňuje myšlenku sémantické konzistence.

Předejít fragmentaci diagramů

• Mít více diagramů může ztížit pochopení architektonického popisu, ale také značné úsilí při jejich udržování. Vedlejším efektem by mohla být fragmentace (např. dva nebo více diagramů ilustrují stejný atribut kvality – výkon, škálovatelnost atd. – ale každý z nich je samostatně neúplný). V takových případech se doporučuje buď odstranit diagramy, které nezobrazují relevantní atributy kvality (spojené s architektonicky významnými požadavky), nebo ještě lépe diagramy sloučit (např. souběžnost a nasazení).

Udržujte sledovatelnost napříč diagramy

• Důležitá je také možnost kontroly historie, porovnávání různých verzí diagramů plus snadný návrat k předchozí verzi. Použití modelovacího nástroje, který toto neumožňuje, může být překážkou. Nejnovější trendy v oboru spoléhají na používání jednoduchého a intuitivního prostého textového jazyka, z něhož se diagramy generují, což zřejmě řeší problém sledovatelnosti. Další výhodou takového přístupu je, že implicitně zajišťuje homogenní strukturální konzistenci mezi diagramy.

Přidejte legendy vedle architektonických diagramů

• Pokud se neřídíte standardním jazykem pro popis architektury (např. UML, ArchiMate), podrobně popište v legendě každou část diagramu (např. rámečky, tvary, okraje, čáry, barvy, zkratky atd.).
• Pokud tomu tak není, stačí v legendě přidat jazyk architektonického popisu jako klíč a není třeba dalších vysvětlivek, protože každý čtenář se bude řídit specifiky tohoto jazyka, aby diagramu porozuměl.

Má význam jazyk architektonického popisu (např. UML, ArchiMate atd.)?

Existuje mnoho názorů na to, který jazyk popisu je v projektu vhodný. Někteří lidé mohou namítat, že jazyk UML je rigidní a není dostatečně flexibilní pro modelování architektonického návrhu, což je názor, se kterým souhlasím. Nicméně v některých případech může být pro zdokumentování základů architektury více než dostačující, aniž by se musel spoléhat na nějaké rozšiřující funkce jazyka UML, jako jsou profily a stereotypy. Podíváme-li se na jiné popisné jazyky, zjistíme, že ArchiMate je ve srovnání s UML výkonnější a vhodnější pro modelování podnikových systémů; existuje také BPMN, který je zaměřen zejména na podnikové procesy atd. Ve srovnávání by se dalo pokračovat, ale nemám v úmyslu dělat nějaký hluboký přehled napříč nimi, protože to není cílem tohoto článku.

Mít architektonický popisný jazyk dostatečně komplexní a flexibilní je velký krok vpřed a mělo by to být solidní kritérium při jeho výběru. Z mého pohledu však skutečná příčina spočívá někde jinde a souvisí s tím, že architektonická dokumentace vůbec nevzniká. Lidé její tvorbu často považují za nudnou, zbytečnou nebo nesmyslnou. Počet softwarových projektů bez dokumentace nebo s nevhodnou dokumentací je obrovský. Nemyslím si, že lidé intenzivně vytvářejí nebo se podílejí na vytváření architektonických diagramů pomocí nevhodného popisného jazyka, a pokud by je nahradili lepším, výsledky by byly zcela jiné. Ne, lidé žádnou architektonickou dokumentaci (včetně architektonických diagramů) nevytvářejí, a co hůř, většina z nich ani netuší, jak ji správně vytvořit. To jsou věci, kterými se musíme zabývat nejdříve – pochopit, proč je dokumentace důležitá a jak ji správně vytvářet (školením softwarových inženýrů); pak přijde výběr správných nástrojů přirozeně na řadu.

Jak lze udržovat diagramy aktuální v průběhu vývoje systému a zhmotňování změn architektury

Existuje několik přístupů k udržování diagramů aktuálních; níže vyjádřím tři z nich. První a nejjednodušší možností by bylo automatické generování diagramů ze zdrojového kódu, který je základní pravdou. To zaručuje, že budou všechny v souladu s kódem. Bohužel se stávajícími nástroji to zatím není plně možné (alespoň pokud je mi známo), protože aktuální nástroje nedokážou vytvořit jakýkoli typ přesného a smysluplného diagramu pouze na základě zdrojového kódu, bez výrazného ručního zásahu. Len Bass řekl, že „ideální vývojové prostředí je takové, pro které je dokumentace k dispozici v podstatě zdarma po stisknutí tlačítka“, což implicitně znamená automatické generování diagramů, ale k tomuto bodu jsme ještě nedospěli.

Druhým přístupem by bylo nejprve navrhnout diagramy pomocí specializovaného nástroje, který by následně vygeneroval kostry zdrojového kódu (např. komponenty/balíčky s hranicemi, API), které by vývojáři později použili k doplnění kódu. Tímto způsobem musí být každá změna v architektuře vyvolána ze samotného diagramu, který může automaticky přegenerovat nebo aktualizovat kostru kódu.

Poslední případ zahrnuje ruční aktualizaci diagramů při každé implementaci nové funkce – která má dopad na návrh architektury. Aby bylo jisté, že se všechny změny kódu promítnou do diagramů, doporučuje se, aby aktualizace diagramů byla součástí definice provedené v procesu vývoje. Tento scénář se doporučuje méně, protože může snadno způsobit neaktuálnost nebo nekonzistentnost diagramů (např. vývojáři často zapomenou nebo nemají náladu diagramy aktualizovat), a to se bohužel stále děje ve většině projektů.

S ohledem na existující nástroje doporučuji jejich kombinaci; kombinovat automatické a ruční vytváření diagramů. Například se snažit automaticky generovat diagramy, které lze rozumně vykreslit nástroji založenými na zdrojovém kódu bez přílišného šumu (např. příliš nepřehledné nebo nesmyslné informace). Do této kategorie můžeme zařadit buď diagramy s vysokou mírou proměnlivosti (např. náchylnější k častým vývojovým změnám, obvykle mající nižší abstrakci), nebo naopak statické diagramy. Některé takové diagramy se mohou týkat kontextových diagramů, diagramů referenční architektury, diagramů balíčků, diagramů tříd, diagramů entit atd. Nicméně v některých případech není pouze na základě zdrojového kódu zřejmé, jak systém splňuje některé atributy kvality (např. dostupnost, škálovatelnost, výkon), a proto automatické vytváření diagramů není dostatečnou možností. Je třeba ji doplnit ručně modelovanými diagramy. Mezi příklady takových diagramů patří sekvenční diagramy, stavové diagramy, diagramy souběhu, diagramy nasazení, operační diagramy atd.

Jaké komplikace (nebo zjednodušení) vznikají u architektonických diagramů, když se zabýváme moderními architekturami (např.např. mikroslužby)?

Mikroslužby nebo jakýkoli jiný moderní architektonický styl (např. bezserverový, řízený událostmi) se řídí pouze strukturou systému, tím, jak spolu jednotlivé komponenty komunikují (např. vztahy mezi nimi) a jakými principy se řídí. Osobně si nemyslím, že by architektonický styl měl měnit důvody nebo koncepty kolem tvorby diagramů (a implicitně i popisu architektury), ani to, co by měly zachycovat. Nicméně pokud hovoříme o moderních architekturách systémů, které mají obvykle vyšší úroveň složitosti ve srovnání se starými a klasickými systémy (např. monolit), rozhodně mají vliv na architektonický popis a implicitně i na diagramy v tom smyslu, že je třeba dbát na více aspektů. Takové úvahy se mohou týkat pochopení počtu distribuovaných komponent (např. distribuovaných mikroslužeb), typu každé komponenty, způsobu, jakým spolu komponenty komunikují (např. hranice, API, zprávy), jejich životního cyklu a toho, kdo jednotlivé komponenty vlastní.

S ohledem na všechny tyto skutečnosti by se měly standardně zohlednit pohledy zachycující dekompozici, vývoj, nasazení a provozuschopnost systému. Představte si například systém s úctyhodným počtem mikroslužeb; v takovém případě by se počet diagramů mohl výrazně zvýšit, protože každá mikroslužba by nakonec mohla mít vlastní sadu diagramů. Problémy týkající se konzistence (např. změna API jedné služby ovlivní dalších X služeb, proto je třeba aktualizovat všechny ovlivněné diagramy), fragmentace (např. vysoká dostupnost nebo výkonnost mezi distribuovanými službami není konsolidována v jednom diagramu) nebo průřezových problémů (např. kdo má na starosti konsolidovaně znázornit aspekty, jako je monitorování nebo zabezpečení, napříč celými prvky systému) by nemusely být snadno řešitelné. Kromě toho se mohou vyskytnout problémy související se soužitím a spoluprací týmů během vývoje projektu, a dokonce i po něm, s cílem jeho udržení.

Shrneme-li to, moderní systémy se složitou architekturou mohou přinášet další problémy, které mohou vést ke komplikacím i na úrovni diagramů.

O autorovi

Ionut Balosin je softwarový architekt a nezávislý technický školitel. Pravidelně vystupuje na konferencích a setkáních věnovaných vývoji softwaru po celém světě, kde přednáší, pořádá školení a workshopy. Další podrobnosti najdete na jeho webových stránkách.