Table of Contents

Notes on software quality #

As a software engineer we often talk about code quality as if it is something all encompassing that we can easily improve. For me, however, these discussions are often fraught with ambiguity and disagreements on what is actually high-quality code.

First, it’s often not clear what we mean when we talk about code quality and we may not even agree on the same thing.

Second, as engineers we are easy to judge whether code is good or bad quality. And we all like to brag about the quality of our code. The fact is however that code quality is often difficult to measure objectively.

Not surprising then that many companies try to jump into this gap and sell you tools to measure and improve code quality. In my experience they mostly work at the superficial level, whereas true issues with code quality are often at a much deeper level.

Although linting tools, code formatters, type checks, and unit tests help, there implementation in the code is also subject to quality.

But what is good quality code and how can you measure it?

External #

These measures are important for the users of the software. Note that these say nothing about how the programming language, data structure, which compiler etc.

Correctness
Usability
Efficiency
Reliability
Integrety
Adaptability
Accuracy
Robustness

Internal #

These are measures that are important for the developers of the code. As programmers we often tend to focus on those, because they make the code more fun to work with.

Maintainability
Flexibility
Portability
Reusability
Readability
Testability
Understandability

You may notice that some of these measures are often at odds. For example, focusing on correctness and reliability may affect performance and efficiency.

The point is that what to focus on is a choice. Some quality measures are aimed at making life easier for the programmer, while some are aimed at making the code easier to use.

Having worked on many different code bases in recent years with varying degrees of ‘code quality’, I think for me it boils down to three things that define high quality software for me:

Easy to change - Code that is easy to change is often well structured, documented, and well encapsulated. This means we can focus on adding new features, and avoid getting stuck in difficult refactoring tasks.
Follows best practices - I’m a big fan of code that follow best practices or community standards. These code bases feel familiar, facilitating collaboration, and gives newcomers a head start when we need to contribute.
Does not surprise me - Code should work as expected. If I have to go down a rabbit hole to chase where that one variable is defined 12 levels deep, it’s probably not a good sign (although we have all been there 😅).