Why are architecture diagrams important in programming code#

Why are architecture diagrams important in programming code#

More specifically, the code walked the pointer graph and made a mirror of it, in the form of lists of vertices and edges - then, it would loop over vertices to print a 'class Foo as Bar >' kind of line for each of them, and then loop over edges, printing lines like 'Foo <- Quux' or 'Foo +. My solution for this was to write a helper function that, when called, would walk the entire graph of those components, and print it in PlantUML form. It wasn't impossible - I designed it to be declarative and locally readable - it was just tedious.

Because it handled wiring up both big and small systems, and was designed to be composable, it wasn't easy to see the entire graph of all the components from code. Random example I did the other day: I wrote a small Dependency Injection library for a project in Common Lisp. These considerations appear to overweigh whatever visual imperfection issues these tools have. * Sometimes you can generate these diagrams from other data you have, pretty easily, and with consistent results. * The formats are not locked up you don't need an authoring license, a subscription, a particular OS to run the editor, etc. * Since the language is open, and no special tools are needed (except a text editor and a renderer on a web page), the diagrams are now everyone's concern and purview, as opposed to the person who happens to be good at graphics. * The amount of visual tweaking the language allows (graphwiz, quite some mermaid, minimal) prevents bouts of bikeshedding and keeps the diagrams focused on their essential parts. You can review, discuss, and approve the changes using tools familiar to every engineer. * Version control! You can diff them and make sensible pull requests when updating some small aspect of a larger diagram, along with text, and possibly as a part of a code change. * You can store them along with other documentation texts.

In my practice across a few companies, diagrams made in code-oriented tools like Graphwiz, PlantUML, or Mermaid were vastly more useful for documenting real, evolving engineering projects. Maybe diagrams made in, say, Visio, draw.io, or Inkscape are fine when you're the sole author of them, and you create typographic quality documentation, a business presentation, or otherwise need eyecandy.