Communicating Design – A Code Review

When was the last time you saw a UML diagram? When was the last time you sat down and discussed how you’re going to design the code you want to write? Do you have a whiteboard handy? Are you working with a remote team? How do you communicate the design of your code?

These are all seriously good questions. As software developers, we sit down with our team and discuss/design our architecture. But how can we communicate that and get external opinions on it from other teams? As we all know, software development is a collaborative process. It’s not a dictatorship with one person deciding the way the project will grow (I hope). It’s a lot of minds coming together and deciding the best way to solve the problem at hand.

So, within a team, you can write this on a whiteboard. Draw your diagrams and then document it somewhere like confluence. What, where, why etc. But why don’t we go one step better? Why don’t we have a living document within the code? At Agoda, we started to do this. We discovered a simple solution you can add to your code now.

Plant UML

Plant UML is a language that will allow you to draw diagrams with code. You don’t need to keep it in a separate repository. You don’t need a separate wiki. You can keep your code-design decisions with your code.

Why is this useful, you may ask? It helps readers of your code to understand the reasons why you architectured your code the way you did. You can use these diagrams to educate and get feedback on future architecture plans.

We used this in my team because we wanted external (other teams within Agoda) feedback. We wanted a living diagram that would reflect our current architecture, that would be easy to maintain, and easy to change. When it lives within your git repository, then you only need to open a PR and your team can see the direction you feel the architecture should go in.

Available in your tools

I’m not sure if an extension is available everywhere, but for Visual Studio Code, there’s definitely an extension available. If you have any other tools that you use for reviewing engineering design and architecture within your projects – feel free to let me know.