4 ms·

> 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

by rewmie 3y ago

> 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. Architecture diagrams document how the software is expected to be organized. They represent the goal, not the current state. The code needs to comply with the diagram, and not the other way around. The only scenario where it makes sense to generate diagrams from code is when we have people trying to onboard to a project that's not documented, and even then these diagrams are only generated once, polished to remove noise, and from that point onward serve as the reference.

hobofan 3y ago
So how would you expect to insight on whether the current code differs from the planned design documents? By always applying a lot of manual human labor?
- growse 3y ago
  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 to something that was hand drawn is not the answer though. For one thing, the code doesn't contain or implement every single important aspect of the design.
  - mnahkies 3y ago
    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 runtime (parsing/validation of inputs & outputs) safe. I can imagine a world where a similar approach could work for higher level architecture. It's pretty common to have a shared helm chart that (largely) defines each individual logical service in k8s environments. Taken to the extreme you could provision your data stores, and network policies etc using this approach such that an individual services chart defines exactly what it depends on. Throw in some metadata fields for descriptions and you're well on the way to having something that could generate some useful diagrams / documentation. Of course the issue with such helm charts is that if you make them flexible enough to suit everybody eventually you'll just reimplement the underlying APIs they are calling - perhaps some approach using direct introspection of k8s resources and cloud resources with a standardized set of metadata to group and describe relationships might be more feasible. For the moment I'll probably stick to excalidraw
    - growse 3y ago
      Sure, but there’s a whole dimension missing here. Architecture is more than simply “what", it’s also "why". It binds the context to the requirements and the desired components< their relationships and interactions. Some other comment described architecture to code as a lossy process, and that’s exactly right. A 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.
- rewmie 3y ago
  > So how would you expect to insight on whether the current code differs from the planned design documents? Developers are expected to know what they are doing and how their software project is organized. > By always applying a lot of manual human labor? That "manual labor" has a name: software development. Software only changes if developers submit changes. Changes are reviewed as part of code reviews.
  - adrianN 3y ago
    In all projects that I’ve worked on the code was much too complex for a single developer to have even a surface level understanding of all of it, yet one is regularly required to change unfamiliar pieces.
    - rewmie 3y ago
      > In all projects that I’ve worked on the code was much too complex for a single developer to have even a surface level understanding of all of it, yet one is regularly required to change unfamiliar pieces. That sounds like a self-inflicted problem, caused by a team failing to develop and maintain their system following basic software engineering principles. I'm not sure how diagrams are relevant.

by rewmie 3y ago

hobofan 3y ago

So how would you expect to insight on whether the current code differs from the planned design documents? By always applying a lot of manual human labor?

growse 3y ago
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 to something that was hand drawn is not the answer though. For one thing, the code doesn't contain or implement every single important aspect of the design.
- mnahkies 3y ago
  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 runtime (parsing/validation of inputs & outputs) safe. I can imagine a world where a similar approach could work for higher level architecture. It's pretty common to have a shared helm chart that (largely) defines each individual logical service in k8s environments. Taken to the extreme you could provision your data stores, and network policies etc using this approach such that an individual services chart defines exactly what it depends on. Throw in some metadata fields for descriptions and you're well on the way to having something that could generate some useful diagrams / documentation. Of course the issue with such helm charts is that if you make them flexible enough to suit everybody eventually you'll just reimplement the underlying APIs they are calling - perhaps some approach using direct introspection of k8s resources and cloud resources with a standardized set of metadata to group and describe relationships might be more feasible. For the moment I'll probably stick to excalidraw
  - growse 3y ago
    Sure, but there’s a whole dimension missing here. Architecture is more than simply “what", it’s also "why". It binds the context to the requirements and the desired components< their relationships and interactions. Some other comment described architecture to code as a lossy process, and that’s exactly right. A 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.
rewmie 3y ago
> So how would you expect to insight on whether the current code differs from the planned design documents? Developers are expected to know what they are doing and how their software project is organized. > By always applying a lot of manual human labor? That "manual labor" has a name: software development. Software only changes if developers submit changes. Changes are reviewed as part of code reviews.
- adrianN 3y ago
  In all projects that I’ve worked on the code was much too complex for a single developer to have even a surface level understanding of all of it, yet one is regularly required to change unfamiliar pieces.
  - rewmie 3y ago
    > In all projects that I’ve worked on the code was much too complex for a single developer to have even a surface level understanding of all of it, yet one is regularly required to change unfamiliar pieces. That sounds like a self-inflicted problem, caused by a team failing to develop and maintain their system following basic software engineering principles. I'm not sure how diagrams are relevant.