Clean Code Is a Style. Clear Code Is What You're Actually Paying For

I saw a piece doing the rounds recently arguing that comments were never really the problem in bad code, structure was. It's a fair point, and it made me think about how often "clean code" gets used as a selling point to clients who have no way of checking whether it's true.

If you're commissioning bespoke software, you'll hear the phrase eventually. A developer or agency will tell you they write clean code, as if that settles the question of quality. It doesn't, because clean code and clear code aren't the same thing, and only one of them affects you.

What "clean code" actually means

Clean code, as a term, usually refers to a set of style conventions: short functions, no duplication, minimal comments because the code should "explain itself", strict separation between layers. It comes from a real and useful tradition in software engineering. Followed sensibly, it produces good results.

The problem is that it's also easy to follow badly. I've seen code that ticks every box on a clean code checklist, tiny functions, zero comments, everything split into its own file, and is still genuinely hard to follow. You end up jumping through eight one-line methods to understand what should be a five-line process, with no comment anywhere explaining why any of it exists.

That's clean by the rules and unclear in practice. And unclear code is expensive, because eventually someone (possibly me, possibly whoever takes this over from me in five years) has to sit down and work out what it does before they can safely change it.

What clear code looks like instead

Clear code optimises for the next person who reads it, not for a style guide. Sometimes that means short, well-named functions. Sometimes it means a slightly longer function with a comment explaining an odd decision, because the reason isn't obvious from the code itself and never will be.

A concrete example: I once inherited a discount calculation that applied a fixed percentage, except in one specific case where it didn't. Nothing in the code explained why. It turned out to be a rule from a contract signed two years earlier that nobody currently at the company remembered. A single comment, "see contract clause 4.2, discount doesn't apply to bulk orders over 500 units", would have saved an afternoon of digging and a slightly nervous phone call to check I hadn't broken something.

That's the kind of thing "code should explain itself" misses. Code can explain what it does. It can't always explain why, and why is usually the expensive question.

Why this matters if you're not the one reading the code

You're probably not going to read your own codebase. That's fine, that's the point of paying someone to build it. But the quality of the code still affects you directly, in a few ways:

• Cost of change. Clear code is cheaper to extend. Unclear code means every new feature starts with someone re-learning how the existing system works before they can safely touch it.
• Cost of switching developer. If you ever need to bring in someone else, whether that's me taking over an existing system or another developer taking over from me, clarity is what determines how quickly they can get up to speed. I've written before about what to do when you inherit a system nobody can explain, and the honest answer is that it always takes longer and costs more when the code doesn't tell you why decisions were made.
• Risk of quiet mistakes. Code that's technically clean but conceptually murky is where bugs hide. Not crashes, those get noticed. Quiet wrong answers, like a discount applying when it shouldn't, that sit undetected for months.

What to ask instead of "do you write clean code"

Since you probably can't judge the code yourself, ask questions that get at clarity rather than style:

• "If I asked another developer to take this over in two years, how quickly could they get going?" A good answer talks about naming, structure and documentation of decisions, not just a style checklist.
• "Where do you write down why something was built a certain way, rather than just what it does?" Comments in the code, a short README, a decision log, doesn't matter which, but there should be an answer.
• "Can you talk me through a piece of this without jargon?" If someone who built the system can't explain a part of it in plain terms, that's worth noting.

None of this requires you to read a line of code. It just means judging clarity by how well someone can explain their own work, which is a much more reliable signal than whether they use the phrase "clean code" in their pitch.

The honest version

I don't follow a clean code checklist to the letter. I write functions the length they need to be, and I comment the decisions that won't be obvious to whoever reads this next, including me in a year's time when I've forgotten the context. That's less about a philosophy and more about having been the person stuck reading someone else's unexplained code often enough to know how much time a single well-placed sentence can save. If you're weighing up developers for a project, that's the thing worth probing, not the buzzwords, but whether they can make their own decisions understandable to someone who wasn't in the room when they were made.