UML v repozitári: Mermaid

Mermaid je z troch exportných formátov najhorší v prenášaní modelu a jediný z nich rieši problém, ktorý väčšina dokumentácie naozaj má. XMI nesie metamodel; .qea nesie metamodel aj rozloženie; Mermaid nesie zhruba to, čo sa zmestí do odseku textu - a vykreslí sa v README bez akéhokoľvek build kroku.

To je celý argument a je dobrý. Diagram exportovaný ako PNG do wiki je do štvrťroka nesprávny a nikto si to nevšimne, pretože nič na zmene kódu nikoho nenúti sa naň pozrieť. Diagram v docs/architecture.md sa objaví v diffe, keď sa jeho súbor zmení, a recenzent, ktorý vie prečítať zmenu, uvidí, že diagram s ňou nesúhlasí.

Aj v dobrých riadkoch stojí za to pomenovať, čo sa stráca: stereotypy, poznámky, obmedzenia a každá stopa po rozložení. Mermaid si diagramy rozloží sám, takže usporiadanie, nad ktorým ste strávili hodinu, neprežije - a pri diagrame, ktorý sa bude regenerovať pri každej zmene, je to skôr výhoda než strata.

Exportujte pohľady, ktoré by vývojár naozaj otvoril, čo takmer nikdy nie sú všetky. Jeden diagram tried jadra domény a jeden sekvenčný diagram toku, ktorý všetci ladia, je lepší repozitár než štrnásť súborov, ktoré nikto nečíta.

Commitujte Mermaid, nie vykreslený obrázok. GitHub, GitLab aj väčšina generátorov statických stránok vykreslia bloky mermaid priamo. Obrázok uložený vedľa zdroja je druhá kópia, ktorá s ním prestane súhlasiť.

Regenerujte, neupravujte ručne. V okamihu, keď niekto opraví názov triedy v Markdowne namiesto v modeli, export prestal byť exportom a obe verzie sa začínajú rozchádzať - a presne o tomto zlyhaní je udržiavanie modelu aktuálneho.