❯On senior engineers and good code

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 infallible meter.

On the other hand, we must resist the temptation of falling in the trap of believing that good code is just another opinion. Probably we just need to dig deeper.

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?

I'll start with a premise:

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 unstated or imagined problems without coordination.

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 want to caution against the trap of assuming that because uncertainty is inevitable, no explanation or remedy is required, and that merely coping with it is a badge 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 or having the tools to overcome 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.

Are we all seniors? Is anybody a senior?

I might be missing something, but copy-pasting from AI seem fundamentally incompatible with being a senior. In fact, if your judgment is based on experience entirely dependent on generated code you are implicitly assuming that the measure of good code is whatever AI generates, because that's the only code you've seen. To tie things together, not only writing code is being delegated to AI, but also our judgment ability is being externalized to a agents we do not control. The result is a further impoverishment of our ability to understand and criticize on top of our diminished ability to solve problems and write software. In very simple terms, we're reaching the situation where AI writes code, and then judges itself.

The habit of copy-pasting from AI is shifting the perception of what "good code" is. If you constantly see and reharse generated code, are embedded in an environment with social pressures to use agents, you read and approve of it, you may be persuaded that (almost) anything that comes out of AI is good, that becomes your new reality. In fact how can you tell it's not real if you hardly ever see anything else? How can you prove you are a senior? You're not writing code, you're not judging it, you're not reading it.

Many new developers have never read the code of a significantly large and complex software written entirely by humans, which means they've never put the kind of effor it takes to understand the logic behind the code, let alone reaching an understanding of the overall approach, philosophy and tradeoffs. They can't write code at that level either and These are important lessons which constitute what we can call engineering culture.

Progressively, even seasoned engineers are losing their problem solving ability by delegating more and more work to AI.

Conclusion

I'm aware that manually written code should not be glorified. The fact that much of what we do every day in software is simple, allows generated code to be sufficiently functional to be uasble in many production systems. Automation is possible, at least to some extent. There is a price to pay though, and I think many don't want to look in that direction: we're implicitly agreeing to unspoken presuppositions. We can't tell who's a senior and what's good code, unless we brazenly accept generated code as our meter, which has its risks and logical inconsistencies. In fact, the definitions of these concepts are as elusive as they've ever been, lost in the layers of abstractions.