Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

The C4 model for visualising software architecture (2017)

c4model.com

Post reply on HN
Print view View original

41–50 of 107 posts

Re: The C4 model for visualising software architecture (2017)

#41

Post by taeric »

ryan-duve wrote: post #3

> 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.

On the contrary, I think auto docs are robbing the team of the ability to think in terms of the higher level of abstraction.

High level diagrams should be disposable and rapid to generate. They are as important for what they omit as for what they show.

Re: The C4 model for visualising software architecture (2017)

#42

Post by nitwit005 »

pjmlp wrote: post #5
IshKebab wrote: post #2

Interesting but I don't think this especially adds anything. The high level diagrams are great but then you can already make those without having to read any fancy visual model websites. The site even kind of admits this: > As an industry, we do have the Unified Modeling Language (UML), ArchiMate and SysML, but asking whether these provide an effective way to communicate software architecture is often irrelevant beca…

UML is still highly used at the architecture command deck, even if the dream to generate code from diagrams failed. Just a couple of months ago I finalized yet another archictecture document, with enough class diagrams, sequence diagrams and use cases on it.

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.

Re: The C4 model for visualising software architecture (2017)

#43

Post by abhishekjha »

ryan-duve wrote: post #3

> 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.

Why is it that compilers don't do this? They have a parse tree for how the sysmbols connect.

Would it not be appropriate to extend the compiler for visualising relationships between software components with zoom-in and zoom-out facilities. Zoom-in takes you to Assembly and zoom-out to the CTO.

Re: The C4 model for visualising software architecture (2017)

#44

Post by joegahona »

almostnormal wrote: post #13
sgt wrote: post #4

Earlier quoted context omitted.

That's what I do. Boxes and lines between them. It helps a lot when thinking up new concepts and brainstorming too, so that the tool doesn't slow you down. I use Freeform now, which is super simple but works. Mark two objects and cmd-click/right click, then click "add connecting line".

One step further: Powerpoint. Sooner or later the diagrams will usually be needed in a presentation. Having them in a presentable format saves another step, and is a constant reminder to produce something worth presenting. Those diagrams that don't end up in presentations will be write-only anyway, and could be in any random format. No-one is going to read them.

That’s a really good point, I’ve had to redo diagrams before to fit them into a presentation, and because they were sprawling all over the place in Figma or Miro, they required extra work to fit correctly and be readable. Powerpoint or Google Slides forces you to concision and the aspect ratio of the slide, for good or bad.

Re: The C4 model for visualising software architecture (2017)

#45

Post by Waterluvian »

ryan-duve wrote: post #3

> 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.

Some problems are people or process problems and can’t always be waved away with tools. Sometimes the answer is to enforce growth of the professional discipline to update documentation alongside code changes.

A way I addressed this was to add a checklist item automatically to PRs, “did you review and update the docs?” And put the docs in the same repo so that a code change will have documentation updates in the same PR. It’s mostly worked but still relies on discipline.

It’s kind of interesting how hard this is for some. The code change is 5 mins. Testing is 20. Documentation is another 10. I’ve seen lots of people not want to do the testing and really not want to do the documentation.

Re: The C4 model for visualising software architecture (2017)

#46

Post by williamdclt »

discodachshund wrote: post #8

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…

I’ve only tried structirizr briefly, but I found it too inflexible. No way to draw concepts that aren’t strictly part of C4. For example I wanted to encapsulate 2 components in a box to represent that they’re currently deployed as one service (not necessarily a good thing to do in absolute but would have helped my team to grok it better): impossible.

I do like the idea of describing architecture formally, but the lack of customizability of diagram output was too painful

Re: The C4 model for visualising software architecture (2017)

#47

Post by mnahkies »

growse wrote: post #21
hobofan wrote: post #11

Earlier quoted context omitted.

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?

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 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

Re: The C4 model for visualising software architecture (2017)

#48

Post by photonbeam »

Waterluvian wrote: post #45
ryan-duve wrote: post #3

> 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.

Some problems are people or process problems and can’t always be waved away with tools. Sometimes the answer is to enforce growth of the professional discipline to update documentation alongside code changes. A way I addressed this was to add a checklist item automatically to PRs, “did you review and update the docs?” And put the docs in the same repo so that a code change will have documentation updates in the same…

Ive seen testing reluctantly tied to “they’ll make me change everything in code review, so why waste the effort yet”

Re: The C4 model for visualising software architecture (2017)

#50

Post by Waterluvian »

photonbeam wrote: post #48
Waterluvian wrote: post #45

Earlier quoted context omitted.

Some problems are people or process problems and can’t always be waved away with tools. Sometimes the answer is to enforce growth of the professional discipline to update documentation alongside code changes. A way I addressed this was to add a checklist item automatically to PRs, “did you review and update the docs?” And put the docs in the same repo so that a code change will have documentation updates in the same…

Ive seen testing reluctantly tied to “they’ll make me change everything in code review, so why waste the effort yet”

Yeah. And it’s possible the process is defective if code review can result in that much change. Oftentimes people skip most of the design process. I’ve been guilty of this.

Reminds me of the army mantra, “slow is smooth. Smooth is fast.” Skipping or rushing design has never actually saved time in my experience. And I see veterans repeating this mistake over and over.

Post reply on HN