• Skip to main content
  • Skip to primary sidebar
  • Skip to footer

Alex Aitken

Technical and Engineering Leadership, Coaching, and Mentorship

Communicating Design – A Code Review

August 13, 2018 By Alex Leave a Comment

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.

Share this:

  • Click to share on X (Opens in new window) X
  • Click to share on Facebook (Opens in new window) Facebook

Like this:

Like Loading...

Related

Filed Under: Coding

Alex

Reader Interactions

Leave a ReplyCancel reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Primary Sidebar

About the author

Alex is an AVP of Engineering currently working at Bukalapak. He is a leader in full-stack technologies. Read More…

Pages

  • Speaking Experience
  • About

Social Profiles

  • LinkedIn
  • Medium
  • ADPList

Recent Posts

  • Interviewing as an Engineering Leader
  • Managing Low Performers
  • Getting Docker, React, .NET Core, Postgres, and Nginx Playing Nice
  • What Makes a Good Software Engineering Manager?
  • “Am I There Yet?” Said an Engineer

Archives

  • January 2025
  • August 2024
  • July 2024
  • October 2023
  • August 2023
  • October 2020
  • May 2020
  • February 2020
  • June 2019
  • March 2019
  • October 2018
  • September 2018
  • August 2018
  • July 2018
  • June 2018
  • May 2018
  • April 2018
  • March 2018
  • February 2018
  • January 2018

Categories

  • Coding
  • Essay
  • Leadership
  • Management
  • Roundtable
  • Strategy

Footer

Privacy & Cookies: This site uses cookies. By continuing to use this website, you agree to their use.
To find out more, including how to control cookies, see here: Cookie Policy

Copyright © 2025

%d