Okay so here's a sentence that's going to sound like nitpicking until I explain it: clean code and clear code are not the same thing. I know, I know, they sound identical. Half of you just read that and went "yeah... obviously?" Stick with me for a second, because this distinction has cost me actual billable hours more than once, and I'd bet money it's cost you some too, even if you never had a name for it.
I run a small dev agency. We do a mix of WordPress/Woo builds, Next.js apps, and a lot of GSAP/Lenis-heavy frontend work for clients who want their site to feel expensive. Which means I inherit codebases. A lot of them. Other agencies' work, freelancers who ghosted mid-project, in-house devs who left before I showed up. And there's a very specific kind of pain that only happens when the code you're staring at is, by every textbook metric, good, and you're still lost.
Short functions ✅. Sensible names ✅. No copy-pasted blocks ✅. Looks like it walked straight out of a Clean Code slide deck. And yet I'm five minutes into a bug fix going "why does this exist" out loud to an empty room.
That's the gap. That's the whole article, basically. Let's actually dig into it.
What people mean when they say "clean code"
Nine times out of ten, when a dev says "clean code" in a standup or a PR comment, they're quoting, knowingly or not, Robert C. Martin's Clean Code. That book is basically load-bearing infrastructure for how a whole generation of us think about code quality. And honestly? A lot of it holds up fine:
- Functions that do one thing, not four things wearing a trench coat
- Names that tell you what a variable is without needing a tooltip
- No copy-pasted logic scattered across six files
- Formatting that doesn't make your eyes bleed
- Nesting shallow enough that you don't need a bookmark to find your place
None of that is controversial. If you've got a function called handleStuff() that's 240 lines long with if-statements nested five deep, sure, go fix that, nobody's arguing otherwise.
But, and this is the part that gets glossed over constantly, clean code is fundamentally a style question. It's about the shape of the thing. Does it look organized? Is it consistent? Would it survive a code review without someone leaving eleven comments? Clean code answers one, and only one, question:
What does this code do?
That's it. That's the ceiling. It doesn't tell you why the code does it that way instead of some other way, and it was never trying to.
What clear code is actually asking
Clear code is a different animal, and it's answering a question that's genuinely harder to satisfy:
Why does this exist, and why does it look like this specifically?
That question lives somewhere nastier than syntax. It lives in whatever the original developer was thinking at 4:47pm on a Thursday when they wrote that weird conditional, and that context doesn't survive very long. It doesn't survive a job change. It barely survives a two-week vacation. Half the time it doesn't survive the weekend, honestly, because we've all had the experience of looking at our own code from a month ago and going "past me, what were you even doing here."
Here's a small example, and I promise it's not a strawman, I've written this exact line more than once:
const MAX_RETRIES = 3;
Perfectly clean. Good constant name, no magic number sitting naked in the middle of a function, passes any linter you throw at it. But why 3? Is that because a third-party API you're hitting starts throwing 429s after three tries? Is it a number someone picked because it "felt right" during a sprint two years ago and nobody's touched it since? Is it load-bearing, or is it decorative?
Clean code cannot answer that. It was never built to. Clear code answers it in one line above the constant, and that one line is the difference between a five-second read and a twenty-minute git-blame spiral that ends with you messaging someone who left the company in March.
The comments argument, and why the "no comments" crowd is wrong about half the time
There's a school of thought, loud, confident, shows up in nearly every "clean code" discussion thread, that says comments are basically an admission of failure. If your code needs a comment to be understood, the argument goes, you haven't refactored hard enough. Extract the method, rename the variable, and the code will explain itself. No comments needed, ever.
I get the appeal. I even agree with maybe 60% of it. A comment that says // loop through the array above a for-loop is genuinely worthless and yes, delete it, it's not helping anyone.
But the "code should never need comments" position falls apart the second you hit anything with real density. Try explaining a gnarly regex through naming alone. Try explaining a bitwise trick used for performance reasons through variable names alone. Try explaining why a form validation deliberately skips one specific field because a client's legal team asked for it after an incident eighteen months ago that nobody currently on the team was around for. No amount of renaming fixes that. The reasoning simply does not live in the syntax, full stop.
And the usual counter-argument ("put that reasoning in the commit message, that's what git blame is for") sounds reasonable until you actually think about when people use git blame. Nobody runs git blame on code that looks fine. You only go digging once something's already broken, once you're already under pressure, and by that point the person who actually knew the reasoning has usually moved teams, left the company, or just forgotten. Commit history isn't documentation. It's a graveyard you visit after something's already gone wrong.
So here's the rule I actually use, and it's short enough to fit on a sticky note:
If you had to stop and think before writing a line, write down what you were thinking. If the line was obvious, leave it alone.
That's the whole heuristic. Not "comment everything." Not "comment nothing." Comment the moments where your brain paused. A comment earns its spot in the code when it's doing one of these jobs, and basically nothing else:
- Translating something genuinely dense (regex, bit tricks, math that isn't self-evident)
- Explaining a decision that looks wrong or arbitrary at first glance but isn't
- Warning the next person what breaks if they "clean up" something that looks messy on purpose
- Recording a decision that has an actual expiry date, not a TODO that's been sitting there since 2023
Everything outside those four jobs is noise. And ironically, a file stuffed with noisy, decorative comments isn't clear either, it's just cluttered in a different direction than messy code is. Over-commenting and under-commenting are the same failure wearing different outfits.
Why this distinction actually costs money, not just annoyance
I want to get specific here instead of staying theoretical, because this is where the agency angle actually matters.
I've taken over projects that scored well on every clean-code checklist you could throw at them. Small components. No duplicated logic. Naming that a linter would happily approve. And I still burned hours because nobody could tell me why a z-index was hardcoded to 9999 on one specific div, or why a scroll animation had a hardcoded 300ms delay that broke the second I tried to make it responsive, or why one form field silently skipped validation while every other field on the same form didn't.
None of that shows up in a "is this code clean" review. It only shows up once you're the person who has to modify it under a deadline, with a client watching a staging link, and no way to ask the original developer anything because that developer is three jobs away by now.
That's the actual cost. Clean code gets you through a code review. It makes a good first impression and it genuinely does reduce a certain kind of friction, nobody's arguing you should go back to writing 300-line functions with variables named x and temp2. But clear code is what determines whether the codebase is still survivable six months from now, when the person who wrote it is gone and somebody else has inherited both the logic and the reasoning behind it, minus the reasoning part.
So which one do you actually chase
Both. But treat them as solving two separate problems, because they are, and fixing one does not automatically fix the other.
Clean code principles get your codebase readable at a glance: good names, small functions, no duplication, consistent formatting. That's the baseline. Skip it and nothing else in this article matters, because nobody can get far enough into unreadable code to even need the "why."
Clear code practices (targeted comments, honest documentation, defaults that make sense without archaeology) preserve the reasoning that the syntax was never going to carry on its own, no matter how well-named your variables are.
Optimize only for clean and you get a codebase that looks great in a portfolio screenshot and still requires a Slack message to the original author every single time something non-obvious needs to change. Optimize only for clear without the clean foundation underneath it, and you end up with comments trying to compensate for logic that's genuinely tangled, which is its own flavor of mess, just dressed up with more prose.
The actual goal was never "clean." It was never really about how the code looks in a screenshot. The goal is understandable, by someone who wasn't in the room when the decision got made, wasn't there for the client call that caused the weird edge case, and doesn't have access to whatever was in your head the day you wrote it.
Genuinely curious how other teams handle this in practice, is there an actual house rule for when a comment is required where you work, or is it just vibes and whatever the reviewer happens to nitpick that day? Drop it in the comments, I want to steal good ideas.
Read More
The Practical GEO Checklist We Use in 2026 — TopBlogs
Ranking on Google isn't enough anymore. Here's the exact GEO checklist we run on every post to get cited by ChatGPT, Gemini, and Perplexity, and what we skip.
topblogs.online
Top comments (0)