Learn in public: Software Architecture, where have you been all my life?

Photo by Yann Allegre on Unsplash

Learn in public: Software Architecture, where have you been all my life?

Have you ever had a simple change request in your application that took way longer that it should?

Alo's photo
ยทMar 21, 2022ยท

5 min read

Recently, I had that experience. A tiny requirement change in one of my project and all hell broke loose. Again.

The project consists of a basic dashboard-like app written in Svelte.

The Product Owner wanted a simple feature removed: the ability to scroll through settings using the mouse wheel.

"I'll be done in 5'!"

Or at least that what I thought. It took me a whole day.

That can't be right.

I asked myself why? This should have been an easy-peasy adjustment. An hour at most. Not a whole day?

I want to go kitesurfing, not spend the day rewriting working part of the code!

Where did it go all wrong?

  • I try my best to write clean code
  • I'm always on the lookout to improve my code
  • I follow best practices and study other people's code
  • I structure my codebase (or so I thought!)
  • I care about the work I produce.

And yet, it seems that my projects build technical debt over time no matter how hard I try.

Is amending a software always more complex than we think?

Can we write code that is easy to extends and maintain? Or are we doomed to have the tech debt build over time?

I came to the realisation that I have been overlooking something important in my coding journey: software architecture.

Alright, folks! The time has come to study software design and keep the technical debt at bay.


What is software architecture?

I'm glad you are asking, Watson.

Wikipedia has a nice definition of software architecture which I'm going to steal here:

Software architecture refers to the fundamental structures of a software system and the discipline of creating such structures and systems. Each structure comprises software elements, relations among them, and properties of both elements and relations. The architecture of a software system is a metaphor, analogous to the architecture. It functions as a blueprint for the system and the developing project, laying out the tasks necessary to be executed by the design teams.

In other words, software architecture is your code blueprint.

Not only does it tell what to build and where to build it, it tells you why and how.

If done properly, this blueprint shows you how to build your system so it remains maintainable and efficient over time.

Sounds like what I'm after, doesn't it?

Not thinking ahead of the architecture is like building a house without plan: you are working blind.


It's all good, I don't need a plan - I have enough experience and I am building a timber structure

Imagine you are contracting a builder to build your house.

You've spent hours with your builder depicting your dream house.

You tell them about your hate for bathtubs; showers only there will be.

You want it to be perfect.

Especially since you might have to sell your left kidney to finance it given the current housing prices... ๐Ÿฅฒ

One day, you turn up on site and you observe them working.

The electricians are on site and they are laying a power cable, they're discussing where it should be placed.

  • "I think there might be a window here soon, maybe we should put it here?"
  • "Yes, but I've put the power box over there, so it's easier if we run it there."
  • "Oh, well it looks like they have just put a bathtub here so maybe we can just go around it."

You have been witnessing the whole conversation. Your reaction?

Three letters and an explanation mark: "W.T.F.!"

You realise the rest of the tradies are not doing any better. On top of that, they don't exchange or discuss with the other trades. Everyone is doing their own thing.

That's a bit concerning ... What is going on here?

You go ahead and chat to them: "Eh guys, I'm pretty sure I didn't want a bathtub, have you checked the plans?"

They shrug: "Plans?"

You realise that they are building your house without any plans whatsoever. None of them have a plan of your house.

You call the builder. They say they don't need a plan, they have build plenty of houses before - why would they need a plan? - plus, they're using timber to build the house.

Would you think: "Oh yeah, right! Of course! Silly me! It's all good, they don't need a plan - they have enough experience! And they're using timber. No worries."

No way! You would be worried. Very worried!

And what is the go with the timber? How using timber for the structure dispense you from having plans?

Going back to the drawing board

Well, unfortunately it seems that is the (wrong) way I have been working so far.

Not only I didn't plan my architecture - but I would use the technology stack as my substitute for a proper architecture!

If you ask me what's my plan, I would say "SQL + React" or "NestJS REST API + Svelte".

Well, that didn't work, did it? When I had to remove this simple feature?

Even using an opinionated framework like Laravel didn't protect me completely from writing a bit of spaghetti software.

I now see that this is the wrong approach to building sustainable software.

You need plan. Having a plan - an architecture - is key to produce successful and sustainable software.

It's time for me to take a step back, return to the drawing board and learn to design software.

So please, be my guest - grab yourself a beer or a cup of coffee and let's talk software architecture.

Let's explore software design together, because let's be honest, the first time you confront yourself with software architecture, you feel a bit like Patrick below ๐Ÿ˜„


Share this