UML v repozitáři: Mermaid

Mermaid je ze tří exportních formátů nejhorší v přenášení modelu a jediný z nich řeší problém, který většina dokumentace opravdu má. XMI nese metamodel; .qea nese metamodel i rozvržení; Mermaid nese zhruba to, co se vejde do odstavce textu - a vykreslí se v README bez jakéhokoli build kroku.

To je celý argument a je dobrý. Diagram exportovaný jako PNG do wiki je do čtvrtletí špatně a nikdo si toho nevšimne, protože nic na změně kódu nikoho nenutí se na něj podívat. Diagram v docs/architecture.md se objeví v diffu, když se jeho soubor změní, a recenzent, který umí přečíst změnu, uvidí, že diagram s ní nesouhlasí.

I v dobrých řádcích stojí za to pojmenovat, co se ztrácí: stereotypy, poznámky, omezení a každá stopa po rozvržení. Mermaid si diagramy rozvrhne sám, takže uspořádání, nad kterým jste strávili hodinu, nepřežije - a u diagramu, který se bude regenerovat při každé změně, je to spíš výhoda než ztráta.

Exportujte pohledy, které by vývojář opravdu otevřel, což téměř nikdy nejsou všechny. Jeden diagram tříd jádra domény a jeden sekvenční diagram toku, který všichni ladí, je lepší repozitář než čtrnáct souborů, které nikdo nečte.

Commitujte Mermaid, ne vykreslený obrázek. GitHub, GitLab i většina generátorů statických stránek vykreslí bloky mermaid přímo. Obrázek uložený vedle zdroje je druhá kopie, která s ním přestane souhlasit.

Regenerujte, neupravujte ručně. Ve chvíli, kdy někdo opraví název třídy v Markdownu místo v modelu, export přestal být exportem a obě verze se začínají rozcházet - a přesně o tomhle selhání je udržování modelu aktuálního.