There are three core reasons why architecture diagrams make sense for even moderately sized codebases:

  • Coherent vision: they provide a clear statement of direction and of decisions made
  • Collaboration: they make it easier to onboard new developers and to work across different parts of a large codebase
  • Outward communication: they're easily consumed by non-hands-on stakeholders.

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

Why are software architecture diagrams important?

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?

Code should speak for itself, right?

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?

Uh, modeling language?

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.

Not only does UML feel like it's from another era but it also has a reputation for complexity. Even its Wikipedia page needs several diagrams just to describe how the various parts relate to each other.

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.

Diagrams are effective when you know why you're using them

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?

How to be sure of why

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

  • are certain of the reason for the diagram
  • know what value the diagram will give you
  • understand the diagram's audience and their needs.

Let's look at some specific examples.

Onboarding new developers faster

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.

Give a new developer good architecture diagrams and you give them the context to understand the code they'll explore in the first weeks on the job. The more they understand the meaning of the code they're working with, the more self sufficient they can be. When they do spend time with existing team members, such as pair programming or in code review, they'll make more efficient use of that time.

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.

Making code changes with confidence

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.

Fixing the problem, not the symptoms

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 can be easy

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.

That's why we've built a solution for creating and updating architecture diagrams automatically. With just nine clicks, CodeSee creates a visual map of your codebase's dependencies. By generating your architecture diagram directly from the code itself, your diagrams become just as much the source of truth as the code itself. And with every merged PR, CodeSee automatically updates the diagram, taking care of the entropy problem.

Request access to our beta to see for yourself the clarity that self-updating architecture diagrams bring to a codebase.