Lightweight Diagrams to Understand your Code


Software Developer






In this constantly changing world, where requirements change from minute to minute, good old diagrams have gone out of fashion. Once the gold standard for expressing how code works, they are sometimes overlooked in modern software development because of their heavyweight nature; they take lots of time to create and they become outdated quickly.

However, diagrams are still extremely handy. In this article I’m going to share how I regularly use diagrams in my work and I’ll explore how to use them effectively.


Why do diagrams have a “bad rep”?

In my experience, there’s two main drawbacks when making diagrams for features: they end up becoming out of date, and making them costs precious time.

Because requirements are constantly changing, the implementation changes too.  updating diagrams every time a design changes, only to change the diagrams again soon, is tiring. In the end, we end up not doing it and the diagrams are worth close to nothing.

Additionally, diagrams cost time, so it’s also a matter of weighing the costs and benefits. Every artifact has a cost: not only to make them, but also to maintain them. If they are not providing enough value, then the balance will tip to being more costly than beneficial.


What place do diagrams have in an ever-changing environment?

Knowing these drawbacks, what’s left for diagrams? There are plenty of ways that they can be useful:

Don’t see them as artifacts, see them as a means of communication

Diagrams don’t have to be static artifacts that are saved for posterity and that have to be constantly updated. You can use them as one-offs! Use them to express what you’re trying to do. In my experience, using a diagram to show all the considerations taken while designing something can replace a long text thread,  thus avoiding confusion and saving everyone time.

Use them in the thought process, not after the design

Has it ever happened that you had a great idea, went on to implement it, and then realized that you forgot one tiny detail that makes your idea impossible? Well, yeah, it has happened to all of us. Making diagrams has always helped me not only to plan ahead a little bit, but also to make problems stand out as soon as possible. If there’s something wrong, it really stands out when putting your thoughts into boxes!

What to take into consideration? (tips & tricks)

Use diagrams-as-code tools if possible and keep them close to the code

If you’re going to create diagrams that should be updated regularly, then it’s of utmost importance to reduce the friction that updating them causes. What’s better than automatically creating diagrams and saving them right next from the code itself!

Using diagrams-as-code tools will allow you to have less context switching, while speaking the same mental language as your code. Another advantage is that you can also save them in version control, check them out in Pull Requests, save different versions, and so on.

Make them when needed!

Don’t forget that diagrams are not a must-do. Use them only when they are valuable, not as a requirement. Imagine them as code comments: if you comment every line then you have a lot of unnecessary stuff written down in your codebase.

Higher risk = Make a diagram

A good way to know when a diagram is needed is to think about the level of risk of a feature. The higher the risk, the higher amount of communication and the higher amount of documentation is probably required. Higher risk features have less wiggle room for undefined details.


How to make them (useful tools)

There’s a plethora of tools out there that allow you to create diagrams. The implementation details may vary (diagrams-as-code, drag-and-drop, etc). You should find the one that fits your workflow the most. These are some of them:

  • PlantUML – This is a great tool to create diagrams with a specific syntax. There’s a desktop app but there’s also a vscode extension which is fantastic for minimizing context-switching.
  • – Formerly known as, it’s a go-to for web based diagrams. It has everything that you could imagine and has plenty of exports and saving options.
  • DBML– More than a tool, it’s an open source DSL (Domain-specific language) created to document database schemas

Wrapping Up

These are some of my thoughts on how to use diagrams that I’ve collected through time. It’s mainly based on my experience, so it for sure lacks several cases where diagrams are useful in a constantly-changing world. What are your use cases and how do you do them?


Like what you read?

Sign up to our newsletter to stay in the loop

What to read next


Crypto: How it started


Crypto: How it started


Micro Front-ends Explained with Jack Herrington