❯What is good code?
A question that's more relevant than ever before.
I'm almost 10 years in my tech career and now that AI has become a common tool in software engineering, the topic of code quality has become more common than ever. Not only we challenge ourselves as human beings to produce quality code (for good or petty reasons), but we have high demands from AI, as counterpart to the incessant rhetorics claiming that code agents can effectively replace humans. Conversations around such topics, presuppose a common understanding of what "good code" is, and as far as I've searched, I've yet to find a consistent definition of what it is.
To be more precise, I'm looking for a definition that:
- is logically consistent, this requirement being self-explanatory.
- Has discriminatory power, that is, it must give us the possibility to distinguish good code from bad code with little to no equivocation.
- Is context-independent(?), in order not to have many different definitions or to at least limit their scope.
I've looked around in popular forums, including on hacker news and and I found many different takes on this subject. I think there are at least two categories of definitions here: some definitions see code quality in terms of intrinsic properties of the code itself, other definitions see it as a property of the relationship between code and the context in which it is written, in other words, quality is not due, or at leas not entirely due to, the code itself. There are of course positions in between.
Definitions that rely on properties of the code tend to be tautological: good code is readable, not overly complex, maintainable etc. But those terms are undefined to begin with. Many tend to define good code in a contextual fashion; quality depends on constraints and the accepted tradeoffs. I believe this is a step in the right direction and that the last requirement I've put in the list above must be relaxed.
I do undertand those that want to maintain a certain purity in the definition, it would be surely advantageous to have a universal meter that always works in gauging precisely the quality of the code. I'm quite sure nobody has such meter nor can think of one.
We must resist the temptation of falling in the trap of believing that good code is just another opinion, probably we just need more nuance.
The problem isn't that code quality is contextual, but that the context itself is often underspecified or partially undefined. For almost any given task, e.g., "implement an LLM-integration", we can optimize for performance or cost, distributed vs localized, highly specialized or easy to modify and general purpose. There are many other tradeoffs.
Two senior developers can produce significantly different solutions, both satisfying the (partially undefined) specification. Afterwards, each may criticize the other's solution as "bad code", but what they're really disagreeing about are implicit assumptions that were never part of the specification.
Where does bad code come from?
My conclusion:
Most debates about code quality are actually debates about unstated requirements.
The incompleteness of specifications forces engineers to supply assumptions. Many disagreements about code quality arise not because people value different qualities, but because they are optimizing for different imagined problems.
A meaningful judgment of code quality must either rely only on explicit requirements or explicitly state the additional assumptions under which the judgment is made.
I strongly warn against falling in the popular trap of believing that uncertainty is inevitable and no explanations or remedy is necessary since dealing with uncertainty is a sign of seniority.
Clearly, uncertainty is naturally present in all engineering endeavors (and also in life), but there is a wide difference between being comfortable with uncertainty and absorb it in any situation and at any cost without being able to challenge it.
The latter situation can quickly become a managerial anti-pattern that pushes senior to the wall of "if you're a real senior, figure it out". A senior engineer's job isn't merely to cope with uncertainty. It's also to reduce it and I'd say, managers should be able to do that too. The answer to uncertainty can't always be "just figure it out".
After months of work, you or your colleagues look back at the code and judge it as "bad code". That's often an expression of unstated requirements and assumptions rather than low skill. The code probably isn't bad, it's written for unstated requirements and priorities that have changed.