3 ms·
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
by layer8 3y ago
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 maintained in conjunction with the code and application architecture, just like textual documentation. There’s just no alternative to simply putting the work in, and making it a regular part of change management.
- simpaticoder 3y agoThe 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 crafted.
- falcor84 3y agoI 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.
- Sophistifunk 3y agoIMO the source code to aspects of the system that are best shown as graphs should be the graphs.
- jakewins 3y agoI realize this isn’t what you’re arguing for, but as a cautionary anecdote on this topic: Paul alludes to it in his post about Healthcare.gov from the other day, but this was apparently one of the major parts of the failure there - endless lines of code generated from UML diagrams, making reading the code hard and things like “can we add a trace statement here” difficult. Optimising for diagrams-as-source-of-truth has drawbacks for debugging and maintainability of the running code https://www.pauladamsmith.com/blog/2023/10/the-10-year-anniversary-of-the-healthcare.gov-rescue.html https://www.pauladamsmith.com/blog/2023/10/the-10-year-anniv...
- bdg 3y agoThis requires a preset architecture standard that explains specifically what boxes and arrows are, and how boxes/arrows interact. Lots of software smears a logical box out over several folders in the code, sometimes even with entirely different names. I don't just mean people write non-cohesive code, I mean frameworks tend to prefer organisation by layer ("the views go in the view folder!") instead of organisation by module ("These things work and change together with a defined boundary"). You can have what you're asking for if you agree to a predefined architecture and everyone agrees to write code that way.
- windlep 3y agoThis is how I use the tool the author created, Structurizr. I auto-generate the initial diagrams, then manually fix it to make it more readable. We then check-in the JSON workspace export into our git repo. The first two levels of the C4 model don't change regularly, so this isn't a frequent process to repeat.
- learn_more 3y agoCheck out https://schematix.com/video/?play=schematix-editing https://schematix.com/video/?play=schematix-editing 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.
- mumblemumble 3y agoAgreed. I experimented with autogenerating C4 diagrams from source a while back, but quickly abandoned the project when I realized that the output was inevitably the flowchart equivalent of bool mystery_func(int i) { // define a new function int x = (int)(i / 2); // x is i divided by 2 and truncated int y = x * 2; // y is twice x return y == i; // return true if y == i } // end of function
- nuancebydefault 3y agoIndeed, the documentation (diagrams/text with particular layout and formatting) should abstract a lot of what the code does. Otherwise, what's the point since the code is there for you to read. In my experience, auto-generated documentation in general does a poor job. That said, such automation is improving by virtue of better AI, that understands and cross translates people's languages and computer languages.
- mpweiher 3y ago> You generally can’t auto-generate useful [architecture diagrams] from code, The question is: why is this the case? IMNSHO, the reason is that we don't have a way to express architecture in or as code. Instead, we have to compile the actual architecture of the system into one that is expressible using the call/return architectural style that our programming languages support. That's a lossy process. When we can program with actual architectural connectors, auto-generating useful architectural diagrams becomes trivial. https://objective.st https://objective.st
- vlovich123 3y agoI don’t think that’s the problem. There are so many different ways to look at a system. An architectural diagram shows you how components connect. A procedural diagram shows you what steps a program takes. An entity diagram shows you the major high level entities you’ve selected into your system. I just don’t see how a single language can express all the detail. Maybe a new one can be invented but I don’t see how S expressions solve this (the link you posted don’t have any indication that any diagram generation is part of the language). Also, diagrams can be useful even if they have birotted because discrepancies are a good teaching tool - “why does this diagram say x but the code seems to do y” is a tracing opportunity, an opportunity to update the diagram, and highlights which engineers are paying attention. Maybe if LLMs get sufficiently advanced they can generate this stuff more automatically with some minor prompting with the code as context, but I doubt it. Not until AI can actually start understanding sentiment from code.
- mpweiher 3y ago> An architectural diagram shows you how components connect. That's the one we're talking about here. > A procedural diagram shows you what steps a program takes Which is useful if the program is procedural. > An entity diagram shows you the major high level entities you’ve selected into your system. That's the top-level of your architectural diagram. > I just don’t see how a single language can express all the detail. When the program's architectural style is call/return, we can do this just fine. Using stepwise refinement we move up and down the abstraction ladder of our system and thus add/remove detail. No problem. The problem is that most systems these days are not primarily call/return, but have to be programmed in call/return languages. > I don’t see how S expressions solve this I don't either, and have no idea what S expressions have to do with this. > .... diagram generation is part of the language It's not part of the language. But it's part of the frameworks, and when the abstractions of your language are architectural in nature, there is a very close correspondence between the code and the diagrams. > ... discrepancies are a good teaching tool... Yes, since the diagrams are generated, it's easy to keep older version around and generate new ones on-demand. Then you can check the differences visually, in code, or as the difference between code and diagram. Take your pick. > Not until AI can actually start understanding sentiment from code. Again, the point is that architecture is not actually "sentiment". It is structural. The fact that it looks like sentiment in practice is purely a side effect of our programming languages being incapable of encoding architecture in the general case.
- rafaelmn 3y agoI use diagrams for two distinct use cases : - planning/outlining a solution - documenting/insight into the system I disagree that second can't be autogenerated - I've used class diagrams, database schema diagrams etc. to visualize projects, a lot of the time over the documentation - precisely because I can trust the generated diagrams to reflect current state. Documentation is nice for context but I'd take good visualisation tools over most documentation I've seen on projects I've worked on. Tooling to connect/validate documentation against code is non-existent, in my world at least. Maybe LLMs can change that down the line - have PR review against docs run as a part of CI/CD pipeline.
- barrysteve 3y agoYou can generate it from code. 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.