81–90 of 107 posts
In other words, no one should change code without first validating those changes with the existing model(s).
> Ideally this diagram would be automatically generated using tooling... The biggest problem I've seen with architecture diagrams is they fall out of sync with the code base. In my opinion, automatic generation of these diagrams is necessary. Otherwise, teams have no way to know whether the picture in front of them accurately represents the latest state of the system.
In my experience diagrams that are pedestrian enough to be automatically generated from the codebase don’t add much value
Ideally, we should be able to visualize state and how state changes. This isn’t a state machine, and it isn’t database modeling. It is an understanding of information flow. Sometimes this flow of information has real-world side-effects (moving a robot’s arm), but mostly this flow is about information being created, transformed, and delivered.
I use the word information because this decouples the visualization from concerns about data and modeling. The important thing is information, not necessarily the way we model that information — those kind of visualizations already exist and are helpful for writing code. But the kind of information flow visualization I’m imaging would help us to understand not how to write code, but what code that needs to be written in the first place.
The most complex pieces of code tend to be buggy when changes are made to them, because they are acting upon state in ways that are essentially complex and interdependent. Wouldn’t it be nice to know that when you update a person’s first name that is is actually affecting systems X, Y, and Z rather than merely systems A, B, and C? Maybe the credit card validation system utilizes the first name in some odd way that your profile page doesn’t, but how would you know that by looking at the code for the profile page? You wouldn’t.
An information flow visualization could potentially identify that. Or maybe not. People don’t usually reference visualizations or keep them updated. A visualization would have to be 10x more useful than they are today to become a routine part of the daily grind of software development, ideally built into the dev experience like IDE type errors are.
Imagine an analog to jumping to a function definition for a state usage — jumping to a visualization of the information you are about to put your dirty paws upon. I suppose this would require a many-to-many relationship between the information flow visualization and state (and anywhere that state was stored, accessed, or mutated).
Fun dream.
Earlier quoted context omitted.
Try testing if people can comprehend the diagrams by asking a question after showing them a somewhat complicated one. You'll likely be disappointed. We don't seem to be using them because they work.
As it happens, most people understand easier a standard notation that can refer to, and get a book at the library, than NIH boxes and lines. Now people straigth out of bootcamps calling themselves engineers, without having a Software Engineer degree, yeah maybe not. Then again, they can get that book I just mentioned, and in the process maybe discover other goodies at the local library, or just ask ChatGPT.
A drawing showing the relationships between database tables seems to be comprehendible to people, until you get to over 7 tables or so, and then they don't appear to be able to make sense of it. Real databases often have magnitudes more tables than that.
You apparently have something you can do a trial with. Show it to people, give them time to digest, and politely quiz them a bit to see if it worked.
Earlier quoted context omitted.
Diagrams are similar to textual documentation: You generally can’t auto-generate useful ones from code, unless the code has extra markup that specifies what to generate. Diagrams often present a specific perspective that emphasizes certain features while omitting others. You might have several diagrams for the same entity, each illustrating a different aspect or scenario. The upshot is that diagrams have to be mainta…
The correct solution is a synthesis: generate the boxes and arrows from code. Then let a human hide, move, and style those objects. When the code changes, the boxes and arrows will change, and perhaps the style will want to change, but at least the diagram will remain correct. This is precisely the distinction between semantic markup and css, btw. Implying that the html would be auto generated, the css would be hand…
Schematix generates diagrams (models) from code which can be entered via the web interface, or from a remote command line or scripts.
Diagrams are rendered on-the-fly from queries called "topological expressions" run against the model. The model must be updated as IT workers change the environment, but since diagrams are generated from code, they always reflect the most up to date information from the model.
> Ideally this diagram would be automatically generated using tooling... The biggest problem I've seen with architecture diagrams is they fall out of sync with the code base. In my opinion, automatic generation of these diagrams is necessary. Otherwise, teams have no way to know whether the picture in front of them accurately represents the latest state of the system.
I get the points about not needing a formalised system for diagrams, even if C4 is quite light touch in my opinion (I never go down to the code level). However, I do have to credit structurizr, which outputs C4 diagrams, as a great productivity boost. One model producing multiple views at all specificities is fantastic compared to mermaid, plantuml, etc, where every diagram needs to be self contained and define and r…
Mermaid's definitely not well-suited for the amount of text and text formatting that C4 requires. You can do it, but you will be jumping through hoops, and the autolayout breaks down pretty quickly when the arrows between boxes get chatty.
> Ideally this diagram would be automatically generated using tooling... The biggest problem I've seen with architecture diagrams is they fall out of sync with the code base. In my opinion, automatic generation of these diagrams is necessary. Otherwise, teams have no way to know whether the picture in front of them accurately represents the latest state of the system.
Diagrams are similar to textual documentation: You generally can’t auto-generate useful ones from code, unless the code has extra markup that specifies what to generate. Diagrams often present a specific perspective that emphasizes certain features while omitting others. You might have several diagrams for the same entity, each illustrating a different aspect or scenario. The upshot is that diagrams have to be mainta…
Diagrams are a flat map of someone's subjective and structured, interpretation of the code architecture.
Words displayed on a computer screen must be developed into supporting subjective knowledge structures.. free from the usual objective mindset of engineering.
You have to go up to first order concepts to get it. The vast majority of (popular) programming culture generates more of the same. Everybody tries to paper over this truth with metadata and it metaphysically does not work.
Computers are capable of much more, they are politically limited down to a small subset of what's possible.
Earlier quoted context omitted.
The correct solution is a synthesis: generate the boxes and arrows from code. Then let a human hide, move, and style those objects. When the code changes, the boxes and arrows will change, and perhaps the style will want to change, but at least the diagram will remain correct. This is precisely the distinction between semantic markup and css, btw. Implying that the html would be auto generated, the css would be hand…
I would actually be really interested in a bi-directional workflow, such that I would also be able to perform system redesign by changing the diagram's connections - the tooling will then automatically update the interface and the tests such that I wouldn't be able to commit my changes until the implementation matches the diagram.