Tuesday, March 18, 2025

Maintainable software requires these three things

For software to be considered maintainable, it requires 3 things:

  1. For there to be (documented) knowledge of everything the software does (and doesn't/shouldn't) do.
  2. For there to be a simple way of verifying the software behaves as intended.
  3. For it to be written in a way that makes it clear to a person looking at the code what it does, so it avoids any unintentional side effects when changed.


Point 1 doesn't require a specific format or way of recording this information. Use what works best for you, the team, the company, and the project.

Point 2 can involve a combination of tools and may require some manual effort.

Point 3 is dependent upon the skills and existing knowledge of the person making a change. It's okay to require a minimum level of knowledge of the language, framework, codebase, etc. The goal, as far as possible and in combination with other requirements, is to have unambiguous code that is clear about what it does. (With documentation--and possibly comments--explaining why, where necessary.)

"As an architect, part of my job is to improve the way we do things"

I was recently listening to a podcast and was struck when the interviewee (a "senior software architect" at a large company) confidently stated that:

"As an architect, part of my job is to improve the way we do things."


Two things jumped out at me about this statement and the way it was made:

  1. It implied that other people at the company don't look for ways to improve things.
  2. It implied that other people at the company aren't allowed to suggest improvements.


I find this concerning.

I consider it everybody's job to always be on the lookout for ways to improve things.

Not that people should be spending a lot of dedicated time focusing on looking at and evaluating alternatives, but that everyone should have an awareness of challenges and opportunities for improvement and should share these when appropriate.

Many years ago, after the weekly developer team meeting at a company I was about to leave, someone else on the team asked why I had suggested a change to a process in that I'd be leaving in a few days.

I made the suggestion because it would be better for everyone working there. Even if that only included me for a few more days.


That other person was happy to be told what to do and then do it. No questions asked.

I don't want to work like that (and probably wouldn't last that long in such an environment.)




Monday, March 17, 2025

Why UI code matters

As a simplification, there are three types of software:

  1. Client/frontend
  2. Headless/backend
  3. Embedded

(Sure, there is some overlap and some things straddle these loose definitions.)

What separates client/frontend software from the others is that it has a graphical user interface (GUI).

I'm a big fan of GUIs.
I like that they make software easier to use because I can see things and don't have to remember as many options, commands, or a set of seemingly magic words to get the software to do what I want.

For many, many people, GUIs make software possible, usable, and desirable.

However, for many developers, creating GUIs can be a source of frustration.

Regardless of whether using markup to describe the structure of the code or an imperative language that describes how to create it, GUI code can easily become verbose and hard to maintain.

If code is hard to maintain it becomes slower and therefore more expensive to modify without unintended consequences and negative side effects.

If spending extra time modifying hard to change code that means less time for doing other work. Such as fixing bugs or adding new features.

There are also the negative emotions and blows to motivation developers feel about having to work with hard to maintain code.

The GUI is also important as it's the part of the application that people (users) see and interact with. It's what many people will know as the face of the application that they may spend hours looking at each day. They may spend more time looking at it than other people or the faces of their loved ones. For something that gets that much time and attention from the people using the software, doesn't it deserve adequate consideration from a development perspective too?


It can be easy to dismiss the GUI as less important than other parts of a code base, but doing so is a mistake.

If it's a "proper" programming language is irrelevant

I changed the way I think about programming when I realised that compiled software is predominantly made of three things:

  1. Binary assets (images, fonts, etc.)
  2. Text files written (and/or readable) by people
  3. Items generated by the above.

It's the second group that's most interesting.

Regardless of whether those text files are scripts, "code" to be compiled, mark-up, or pretty much anything else: if people are going to read (and/or write) it, isn't it beneficial that those files:

  • are easy to read
  • are easy to write
  • are consistently formatted
  • use meaningful words (names) to aid comprehension 
  • are unambiguous 
  • avoid duplication 
  • are succinct (so as to avoid unnecessary verbosity)
  • highlight issues/mistakes (or make them easy to spot)
  • have good/appropriate tooling to aid in working with them

When this isn't true, those files are harder to maintain. This makes making changes lower and, therefore more expensive.


99.985% of coding is maintenance*

Maintaining code means changing it.

Those changes could be alterations to what's already there or in addition to what exists.

This isn't only true once a version has been released or shipped.
This is also true during initial development. 

Once there is other code, this needs to be read and understood, and additions/changes made in light of what already exists. 
Whether there is one existing line of code or one million; if what exists is hard to understand and reason about, future alterations to the code can be hard to integrate and risk unintended consequences. Both of which take more time/money. 

Maybe that's not a problem for you, but every developer I've ever met has more things they need to do. More bugs to fix, more features to add, or new products to create. Having more maintainable code means they get to more of those things; and faster!

Optimize for maintenance (ease of reading/comprehension) to save time/money in the short, medium, and long terms.


* Not a fact but an educated approximation.