Software should be Correct first, then Clear, then Fast
Most software is built Correct, Fast, Clear, and it becomes a painful house of cards.
TL:DR
When writing software, being correct should be the top priority, because if it is not correct, then the code is not doing the basic thing that it was meant to do.
Beyond being correct, clarity should be prioritised over performance, because it optimises for iteration speed over execution speed, which is, usually, a lot more valuable to a business.
Performance should not be neglected, but should be prioritised once there is good business case. It should not be prioritised preemptively.
What do I mean by Correct / Clear / Fast?
Correct
The thing you’ve written does the job it was designed to do.
Sounds like it would be obvious, but this is probably the hardest part of writing any piece of software. Does it fulfil the requirements? Does it have bugs? Does it work enough of the time to be acceptable for use by the user?
Writing something that actually solves original problem is difficult and should not be underestimated.
Clear
The software has been written in a way that is as easy as possible to understand.
What does ‘clear software’ mean to you?
It can vary quite a bit depending on who you ask. For me, clear software is software that can be picked up without needing to know all of the context and can be done by someone with a limited background in software. It is code that is excruciatingly obvious, so that it is almost impossible to misunderstand what it is trying to achieve.
Fast
The software does it’s job in a short period of time.
Short is relative, short for a website responding is probably going to be different for short for a batch job. To me, fast means software that is fast enough that speeding it up anymore would not be worth the effort it would take to achieve that performance gain.
Important note: Fast and Clear code are not mutually exclusive necessarily, you can write something that is both easy to read and lightning fast, it just takes more time / effort. Often we are not fortunate enough to be able to spend the time to do both.
What about Fast, Correct, Clear?
Homer: “Remember kids, there’s 3 ways to do things: the right way, the wrong way, and the Max Power way!”
Bart: “Isn’t that just the wrong way?”
Homer: “Yeah, but FASTER”
Writing fast but incorrect software is not useful. Sure it runs quick but does the wrong thing. Similar to putting Clear as the first priority, sure, everyone can read it, but it doesn’t matter because it doesn’t work and will need to be changed until it does.
Correct needs to be the top priority.
If your software is not correct, it is fundamentally missing the point of what it was trying to achieve.
What about Correct, Fast, Clear?
In my experience, this is the way a lot of software is written.
This is especially true of engineers that are new to software, they are enthusiastic to demonstrate all the knowledge they have gained. Wanting to show that they know what a cache is, how multithreading works, or they want to write some form of graph algorithm.
This is not something exclusive to new engineers either, engineers of all levels feel this, the need to use that fancy framework / tool that will solve all the problems they had in the last project, make everything happen instantly and scale out to 16 billion users per second.
These things are all fine in situations where they are appropriate, but those situations are less frequent than many engineers would like.
I should say, I have no problems with engineers being enthusiastic and wanting to show all they have learned, quite the opposite, I love working with enthusiastic people with a passion for getting better.
That enthusiasm sometimes needs to be tempered with the uncomfortable reality that most of the time we are not writing netflix scale deeply complex and mathematical applications. Most of the time, we are trying to model some domain in the real and imperfect business world into the realm of software. That mapping will usually be something simple, like a database with a service sat on top of it.
The house of cards
Correct, Fast, Clear are the projects that yield systems similar to a house of cards. Sure it works, and it works fast too, just don’t try make it do anything else.
Businesses are constantly evolving, trying to outcompete each other, trying to build something that more accurately fits their user’s needs. This tends to translate into a constant need to tweak a feature that has already gone out, or or to add new functionality. We’ve all felt this, the need for the business to have it’s new shiny feature instead of dealing with the technical debt.
This becomes a problem, refactoring a house of cards is at best, painful and at worse, impossible.
On the painful side, a long time for refactors leads to features that are delivered slowly, the business being less able to compete, slowly becoming irrelevant, and your role along with it as you work to maintain the house of cards.
On the impossible side, if a project is no longer capable of being adapted, it needs to be rewritten. There will be a big fanfare as a new team of engineers are spun off to write the project again, from scratch, using the new technologies. This big rewrite, if it goes well, which is not guaranteed, will use a lot of time and money that could have been better spent on something else, if the original project had been less of a pain to deal with.
Clear > Fast
When we choose fast over clear, we optimise for software execution speed over business iteration speed.
Choosing clear over fast, we make a codebase that is tuned towards other humans reading and understanding the project. It is simpler, sometimes naively so, but it becomes easier to refactor and debug.
This is good for the business because they can get their shinies faster, it is also good for the engineers because they spend less time trying to keep the wheels spinning on a monstrosity, fewer support calls at 3am.
We spend so much more time reading code then we do writing it, we should optimise for the experience of the people who work with our code over the experience of the computer that is going to run the code. The speed at which software can be changed is more useful to a business than the speed at which it runs.
When should software be fast?
Given the question: “Should I prioritise clear code over fast code?” my response would be, It depends…
There are of course, caveats to prioritising clear over fast, there is a limit to how slow we can make code before we start negatively affecting the business. This will depend from one business to another, one project to another.
In my experience, you’ll have 3 types of code in your project:
- Code that gets called very infrequently, probably on startup, used to set up the environment in which the main part of the code will be run
- Code that gets called occasionally, often these will be doing things like creating or updating entities, things that involve the very complex business logic.
- Code that gets called very frequently, usually the code that retrieves information and displays it, or the code that is run on every request as part of monitoring or security and the like.
The code that is called very frequently tends to be a pretty small amount of code relative to the rest of the project, which is made up of the infrequent and occasionally called code.
The code that is being called infrequently should definitely prioritise clarity over performance. Making something that took 1 second take 0.1 second, while an impressive 10x improvement, is pointless, if it gets run once a week when the code is deployed and nobody notices the difference.
The code that is being called occasionally, should lean more towards clarity over performance. Especially if this is the code that contains the particularly complex business rules, this is the code that will be changed most often and it is the code that would most greatly benefit from being easy to work with. The time when this would need to prioritise performance is if there is a clear business need to make the process faster.
The code that is called very frequently, should still be written in as clear a way as possible, it should then be optimised for performance only if it has been identified as a bottleneck.
So to try an answer the question, when should software be fast. I think it should be written clearly first, then made fast if the software is:
- Being run frequently enough that speeding it up makes some appreciable difference.
- Clearly identified as a bottleneck and backed up by data, rather than being the first thing that someone thought of while trying to diagnose a problem.
- Capable of being made fast enough for the business purposes, without needing to spend too much time doing so.
The last one is more a statement about not speeding up a piece of software to a degree beyond the business needs. For example, if a team spent a year speeding up a platform so that it can execute requests in less than 1ms when 4 weeks and 100ms would have solved the business problem.
When should software be clear?
It depends, of course, however, in my opinion, software should always be written in the clearest and simplest way possible first. Then only made less clear if there is a pressing need.
To me, clear could be that I:
- Use a couple of iterations through a list where something might have been done in one iteration, but with lots of nested logic.
- Call an API twice to get an object by ID if it means I don’t need to keep passing a complex object down through lots of layers of code that do not need to know about it.
- Create a new object and copy over details rather than mutating an existing object, if that means less chance of confusion from side effects.
These are just vague examples, it very much depends on the code being written.
The key here is that clearer code might be slower, that’s OK, because we write software for people, not for computers.
Summary
Software should be written to prioritise for being Correct first, then being Clear, then being Fast.
- Being correct comes top because if the software isn’t correct, then it has fundamentally missed the point of what it set out to achieve.
- Being clear comes second because we write software for other people to read. Our code is read a lot and by making it clearer we optimise for business iteration speed
- Being fast, should not be neglected, but it should come once the code is both correct and clear.
About the author
Hi, I’m Doogal, I’m a Tech Lead that has spent a bunch of years learning software engineering from several very talented people. When I started mentoring engineers I found there was a lot of knowledge that I was taking for granted that I think should be passed on. These stories are my way of trying to pay it forward.
