61–70 of 107 posts
Code is too multidimensional to be approximated with 2d drawings. It just doesn't work.
What could work are more conventional architectural code patterns. Things like structured concurrency, but also for higher level. Maybe.
That being said, the biggest issue I ran into is in the diagram tooling. At the time we had Gliphy. One could not make it interactable, such that double-clicking on a node would explode the container and let someone drill-down. At best they had layers which were awfully crude to work with. And at the end of the day didn't export in SVG so were useless for embedding. Overall, a waste of time. :(
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…
Agreed. 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
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.
> 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…
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.
Earlier quoted context omitted.
This is not a trivial problem to solve. Some would say that one of the entire points of software engineering is to assure that the code meets the design spec. A more rigorous approach would be to encode your design as a bunch of linting rules that you could run against your codebase (IaC and all). I'm pretty sure that auto generating a diagram from some code and then trying to work out if it's semantically equivalent…
Yeah it's hard. For http API design I like to start with an openapi spec then generate as much of the server and client library implementation from this as possible. The spec gives a language/implementation agnostic way to describe what you're intending to build that's nicely diff-able over time, and you can generate a lot of the boilerplate that's easy to screw up in a way that's both compile time (static types) and…
Architecture is more than simply “what", it’s also "why". It binds the context to the requirements and the desired componentsA diagram is not "the architecture", it’s simply a view on it, or a "projection of the model" as the c4 folk like to express it as.
I just find the idea that we should automate diagram production because diagrams are hard to keep up to date a little quaint, because you hardly ever need to update just a diagram when changing the architecture. So your actual problem is that your design documentation is hard to keep up to date, and that’s a process problem. Generating diagrams from code won’t save you there.
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.
I do not believe this for a second. You're possible arguing against a straw man.
The alternative to UML isn't a "NIH UML" which uses a different array of arrows. It's labelled boxes and lines. You don't need to go to a library to understand the diagram because the diagram is self-explanatory.
Here's a really good example:
https://buck2.build/docs/concepts/concept_map/
Every arrow is labelled. No tedious textbook needed.
Earlier quoted context omitted.
But you don't need and official standard that everyone learns. Just use words. If your box is a class, write "class Foo". If your arrow means "contains 1 or more" just write that next to the arrow.
Yes, that’s exactly the convention that C4 specifies: add legends on every diagram and make sure things are labeled in a way that people can understand.
Earlier quoted context omitted.
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.
> 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. I do not believe this for a second. You're possible arguing against a straw man. The alternative to UML isn't a "NIH UML" which uses a different array of arrows. It's labelled boxes and lines. You don't need to go to a library to understand the diagram because the diagram is s…
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…
> 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 prog…
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.
You can see a crappy house that’s falling apart pretty easily. Conversely management cannot see a crappy codebase that’s rife with technical debt. Maybe they would make more intelligent decisions if they could visualize the problem.
Code quality does not seem to have any correlation with business success. Why should business care?