Why create software architecture diagrams?

By Matthew Revell

So, then, why aren’t they a core part of every software development project?

Imagine this.

You join a construction project as a contractor and the construction manager gets you up to speed. They start by telling you that it’s a steel frame building with precast panels on the exterior. Then they show you a handful of hinges, a few pipe connectors, and an unopened bag of cement.

With that they advise you to start prodding around at what’s already been built and then they leave for their next meeting.

You’d be confused and, no doubt, you’d question the competence of everyone involved.

But, of course, this wouldn’t really happen on a construction site. So, why does it feel uncomfortably familiar for us as developers?

Part of the answer is to do with history. Attempts at describing codebases have often been imperfect.

That’s because code isn’t like a building. Code is its own source of truth. Use other ways to describe it and you can easily introduce entropy, where the diagram gradually diverges from reality.

Even if there is an architecture diagram, it can be hard to get the level of resolution right. For a civil engineering project, there are well understood standards. But for code it’s not so clear. Do you map out the broad components or do you dive into the specific interactions between functions and objects?

And then there’s UML whose answer is to get as deep into the weeds as possible.

For many developers, architecture diagrams are synonymous with this visual language and the mid-90s rush to object oriented programming.

And perhaps it’s not entirely UML that’s the problem but rather the way it was used early on.

Rather than describing the reality of a codebase, some teams set out to use UML to design solutions before committing anything to code. There are even stories of enterprise software projects where architects spent years drawing UML diagrams without a single line of code being written.

The first step to answering, “Why create architecture diagrams?” is to ask another question: what underlying problem are you looking to solve?

The answer you give will almost certainly change depending on the phase of your project and the audience for your diagrams.

In the early design phases, it’s the act of creating the diagram that’s important because it enables systematic thinking. Later, diagrams are primarily communication tools that provide a record of decisions taken and act as learning aids.

But whatever stage you’re at, if there isn’t an agreement between everyone working on a codebase as to what its architecture is then can you really say you have an architecture at all? Don’t you instead have an emergent phenomenon that just happens to work?

So, if you want software architecture diagrams to be useful, rather than ritual, then make sure you:

Let’s look at some specific examples.

Onboarding new developers onto a project is rife with bottlenecks.

Every moment that an experienced team member spends teaching a newcomer the ins and outs of a codebase, for example, is time that they’re not working towards that sprint’s tasks. Maybe that’s short termist but it’s the reality, for many dev teams, of juggling business demands with team responsibilities.

Throwing new developers in at the deep end is kind of on brand for an industry where one of the most popular learning websites has an underlying culture of assuming people are both wrong and stupid. But it’s harmful gatekeeping. Architecture diagrams aren’t the sole solution but they’re a step away from the idea that not knowing something is a weakness and towards enabling good people to make their contribution.

Medieval mapmakers had good reasons for not knowing every cove, mountain, or stretch of ocean. But what excuse do we have for all the “here be dragons” warnings in our codebases?

Architecture diagrams offer us the kind of satellite view that those old cartographers would have probably considered to be cheating. A visual expression of the interactions between different components makes it easier to reason about the potential impacts of changes. Rather than fearing unintended consequences, a developer working on a well documented codebase has a better chance of anticipating what a change in one place will mean for the wider system.

Even if architecture diagrams can’t solve brittle code they can at least serve as a ledger of technical debt.

Let’s turn to another analogy. In fact, it’s old — at least 2,500 years old — so let’s call it a fable.

The fable is all about how a close-up view of small parts of something larger won’t necessarily explain the whole. It goes like this: four people try to understand an elephant by touch alone. Each one touches a different part of the animal — a tusk, the tail, the trunk, a leg. They each gain a different view of what the animal is: a spear, a rope, a snake, and a tree.

In the heat of a crisis, we often do something similar. We peer closely at the parts of the codebase where we believe the problem lies. Not only does that mean we try to understand a system by focusing at the micro level but, if we don’t have a software architecture diagram to turn to, we try to do thoughtful analysis when our brains are ramped up on adrenaline.

The result can be something that works in the moment but doesn’t solve the underlying problem: the much vaunted root cause. With a visual aid to understand how the parts of a system interact, it’s easier to discover where that root cause might lie and, perhaps, to get some clarity on what particular set of circumstances made the whole thing fall apart when it did.

Architecture diagrams are an essential part of other engineering disciplines and we at CodeSee believe that software engineers can get more done, with fewer headaches and compromises, if they too have tools to understand and visualize their work.

Related posts:

Je suis au travail depuis une vingtaine de minutes. Il n’y a quasiment aucun collègue. L’activité est absente. J’ai enfin reçu participation et intéressement. J’ai directement mit 1000e de coté. Il…

Microsoft provides reliable products and has continuously innovated with technology to come up with new and improved products. The office program comes with enhanced efficiency as it enables the…

Edward II was not expected to become king, as he was the fourth son of his father, King Edward I. However, his elder brother Alphonso died in 1284, leaving Edward as the next in line to the throne…