What ‘high quality code’ means
Philosophy, praxis and examples
Imagine you knew the materials destined to build homes and vehicles were flawed. Would you still build with them? Or if you knew that the ingredients that will go in your food were spoiled. Would you still eat them?
The quality of the building blocks that make the lives we live determines the quality of our lives.
Software has also become a core element of what makes up our daily livelihoods, which means that the quality of the software we code (and use) will significantly influence the quality of our future.
Humanity has made that mistake in the past: fossil fuels, plastic, greenhouse gases, pouring waste into potable water sources, and the list goes on.
Short-term benefit often hides mid- and long-term loss.
A lot of articles can be found on high quality code. Pretty much all of them are structured as a step-by-step guide to write good code, but no one can actually believe that an article can teach someone how to do that. This is not one of those.
Manas.Tech is an organization known for the quality of the code it produces, with nearly two decades of developing high performing software tools. So, instead of trying to write yet another impossible tutorial, we want to focus on gathering the combined knowledge of our engineers to find some insightful criteria that points us in the direction of how good quality code is conceived, designed and built.
How to know when we got there
A quick online search throws a bunch of different perspectives and definitions about this topic, but if we read carefully into them, they all end up sounding more and more like opinions. Sometimes, they even come across as an attempt at SEO, aiming for positioning at the expense of clarity and insight. But we’re not trying to find the best answer to a prototypical user’s search terms, we’re trying to come up with useful, applicable guidelines that shape the way we approach building sustainable, maintainable and efficient code.
So, why do we want a good definition of high quality code? Because we need a methodical and objective way to determine that we’ve created code that is high quality. Why? Because, as we said, software is now a core element of most of the products and services that our lives are built upon. Uniform criteria to determine the quality of the systems that make up our world becomes a requirement.
So, having a good sample of experienced software engineers at hand, we decided to survey our team to try and come up with a solid, functional definition of high quality code.
Survey
The questionnaire was brief by design. We wanted to get meaningful answers, but not take a significant amount of time from our engineers. The goal was to ask ourselves how we create and deliver high quality code, which could also serve as the foundation for building a document that reflects how we think about code and our everyday practice. Also, we didn’t want respondents to lose interest and lower the quality of their answers just to get it over with.
One of the items in the survey was «What is the first question you try to answer when evaluating the quality of code?», a question aimed to surface the respondents point of entry to code review. Across the board, the answer was «What does the code do?». It sounds common-sensical, yes. But it points to a very functional-oriented evaluation, which starts to say something quite interesting when we look at other questions in the survey.
For instance, when asked what attributes our engineers rank the highest as a symptom of good quality code, the first response was clarity, followed by effectiveness and simplicity.
Good quality code is clear about what it does, it does it well, and it does so simply.
A nice complement to this view is that, on the opposite end, most of the surveyed engineers pointed that a symptom of bad quality code is high complexity. This reminds me of Ozzy Osbourne saying:
«I don’t want you to play me a riff that’s going to impress Joe Satriani; give me a riff that makes a kid want to go out and buy a guitar and learn to play.»
But I digress.
Aside from high complexity, other high ranking indicators of bad code were :
- «another developer’s difficulty or incapacity to explain or understand what the code does»
- «a lack of clarity», and
- «a lack of post-reflection».
Basically, bad code looks like a mess. Not only it is less efficient, sometimes even inefficient. It looks messy to other developers. It gives them a hard time understanding what it is and what it does. And that points towards a developer who has difficulty with creating good abstractions. Which is another way of saying that they haven’t taken the time to fully understand the nature and complexity of the problem they’re trying to solve. As Einstein said, «If you can’t explain it simply, you don’t understand it well enough.»
What it all means
This survey gives us a glimpse into what high end software engineers think when designing, building and reviewing code. We did our best here to boil all of that down to a summary of indispensable attributes that make for good quality code, and something more like a rule of thumb to identify bad quality code.
This is not enough, though. Building high quality software doesn’t necessarily take more time or even cost more, but it does require a careful and methodical approach that usually means that the engineers behind it have spent more time thinking about the problem (and have previously spent more time thinking about other problems), exercising their craft and polishing their skills.
The problem is that, most often than not, we don’t know when building materials are of poor quality or that the food we eat was prepared with less than ideal ingredients. And, more often than not, we notice the quality of the code because it is bad, precisely because of the negative consequences it brings. As Nassim Taleb puts it:
We see the obvious and visible consequences, not the invisible and less obvious ones. Yet those unseen consequences can be — nay, generally are — more meaningful.
Good quality software is kind of like running water: we open the tap and expect it to flow. And as long as it does, we don’t really reflect on how that came to be. We only notice it when it doesn’t, when our expectations are missed.
So, what does «high quality code» mean?
It means that someone put in their time, effort and long term developed skills into designing, building and expressing the solution to a problem in a way that works and creates a good base for continued evolution. As mentioned earlier, that quality translates into the quality of the life we can expect to build on top of it. So, any way we want to look at it, good quality software is a smarter investment than the alternative.
We want to strive for good quality code because the nature of business is to constantly change, and that makes requirements change, which leads to changes in functionality. So, then code needs to be modified, in order to adapt to the new business requirements.
What if we build architectures that expect change? That is the very question asked by Neal Ford, Rebecca Parsons and Patrick Kua, in their book Building Evolutionary Architectures. What if, instead of aiming to build something that fights off change, we built systems that flow with it. After all, change is the only constant.
From that point of view, high quality code is code that any developer can easily understand what it is doing, how it is doing it and how to change it so that it does something else.
High quality code and evolutionary architectures go hand in hand, and that should be the primary indicator of a successful software endeavour.
First and foremost, because software is the language spoken by most of the things and systems that make up our everyday lives: we are way more dependent on software than we realize, and a lot of the situations we regularly identify as unfair, impractical or frustrating, are the product of not understanding the situation with enough clarity, which leads to poorly designed systems and mixed and matched code that keeps growing in complexity in a futile attempt to get those poorly designed systems to fix the reality they don’t fully grasp.
Second, because the attributes of clarity, effectiveness and simplicity are not merely a whim, or a stubborn quest for elegance, but a fundamental way to build robust solutions that can stand the test of time, adapt to an evolving technological landscape, and serve as the foundation for future developments.
And last but not least, because any corners we cut today will create headaches, turmoil and even catastrophe for the future. As creators, as contractors, as clients and even as consumers, we should own up to that responsibility.
Wherever in the ecosystem you are, you can step up and demand high quality code. It makes a real difference.
Originally published in the Manas.Tech blog
