Clean code, clean decisions.

Clean code, code quality, refactoring code, tidying up. Whatever name you give it, the difference between a messy codebase and a clean one is unmistakable - to software engineers.

To those outside, looking in, our frustration working in an unclean codebase can be mystifying. And our needs for time to clean our code can appear anywhere from surprising to downright baffling.

Code is, frankly, byzantine to those who can’t read it. So it should be no surprise that quantifying the value of turning ‘messy byzantine scratchings’ into ‘clean byzantine scratchings’ can be difficult.

Software is decision making

Software engineering is decision making all the way up and all the way down.

  • Barry Hennessy1

I think that viewing ‘clean code’ through the lens of decision making can give us a good understanding for its value.

For decisions you need some options. And to think up those you need context and constraints.

Business, project and tactical context and constraints should come from your project tools, documentation and simply being aware of what your team is doing.

But programming context and constraints is encoded in your project(s). It has to be found and understood. It’s embedded in your program, tests, databases, deployments and dependencies. And it is constantly changing.

Finding and making sense of programming context and constraints is why clean code matters.

Understanding drives decisions

As software engineers we are constantly gathering context. This is costly to us, in both time, and effort. And it’s costly to the business, in money and poor decisions.

Time is money

Bill by the hour, day month or project; be employed or freelance; it doesn’t matter: Software engineers cost money and our time is expensive2.

Code is hard to read. Big surprise. That’s one of the reasons software engineers are worth so much; we can navigate and wrangle this Byzantine landscape of code, compilers, cloud and…. cruft3.

It can be easy to understand the goal of a task; what change to make. But often the time spent ‘programming’ is finding out where best to make that change. How the different places you could change affect the work around it. And what side effects they all have.

This is gathering context. And it’s a big part of our job.

Clean is fast

The cleaner and clearer a codebase is the faster you can navigate it, build your mental model and decide where to make your change.

A clean codebase has clean interfaces, types, API’s etc. These all serve to speed up answering the questions:

  • Is this the right place for the change I need to make?
  • Will this change, here, have any side effects? Is it safe?

As with anything software; there are details. But the core of it is this:

Clean code saves engineers time gathering context. They can quickly make confident decisions. And that saves your business money.

Managing clean

So the next time an engineer asks for (or demands 😣) time to refactor, clean their code, improve documentation etc. try to understand it through the lens of context gathering and decision making:

  • How long do they spend gathering context to make a change?
  • Is it often unclear how or where to make a change?
  • Do they find themselves unable to be sure if a change is 100% safe? Does it slow them down?
    • Put another way: are they confident deploying, but surprised when changes have unexpected side effects and break systems?4

And, engineers, the next time you find yourself struggling to navigate a nasty piece of code, start gathering answers to those questions:

  • How long are you gathering context for?
  • Is it unclear where to make a change? Why?
  • Are you worrying about side effects? Which ones?

When your head is clear, then weigh the cost of the status-quo and value of cleaning up5. Talk to your team and try framing the positives of cleaning up as quicker context gathering and improved decision making.

Postscript: context switching

Software engineers often deplore time lost to context switching.

Gathering context costs energy and time. Context switching is, roughly defined, when our attention is broken from our focus (where we’re gathering context) to something else and, after some time, back again. The context we’ve lost has to be re-gathered; costing us more time and energy.

It’s not too hard to see that an unclean, difficult to navigate, difficult to understand, codebase will amplify the cost of context switching. You have to re-navigate and re-remember where you were and what you had already checked.

It’s unavoidable, but too much of this switching and you’ll have some very frustrated engineers6 on your hands.

I do have some simple, if crude, methods to combat context switching, but that’s an article for another day.

  1. #selfquote ↩︎

  2. Expensive, not precious. Everyone gets the same 24 hours of the day. ↩︎

  3. noun computing, informal. Redundant, old or improperly written code, especially that which accumulates over time; clutter.

    https://www.wordnik.com/words/cruft ↩︎

  4. It’s worth noting that side effects aren’t always visible when you deploy. e.g. subtle database side effects can lie in wait for a long time before making a real mess of your system. ↩︎

  5. Remember, cleaning up costs time too; focus your scope for the highest bang for your buck. ↩︎

  6. I’m sure this happens in other disciplines as well. ↩︎