"Clean code" advice has a reputation problem — some of it is dogma that makes codebases worse. Here's what's actually held up after years of maintaining production systems.
Holds up: name things for the reader, not the writer
// Bad — clear to you right now, opaque in six months
const d = calc(u, 0.08);
// Good — clear to whoever reads this next, including future you
const totalWithTax = calculateTotal(unitPrice, taxRate);Names are the cheapest form of documentation you'll ever write. Spend the extra ten seconds.
Holds up: functions should do one thing, but "one thing" is contextual
The rule "functions should be 5 lines long" doesn't hold up — plenty of correct, readable functions are 20-30 lines when they represent one coherent operation. What actually matters: a function shouldn't silently do two unrelated things (e.g., saveUser() that also sends an email as a side effect nobody asked for by name).
Doesn't hold up: avoid comments entirely
"Code should be self-documenting, comments are a code smell" is repeated a lot and is wrong in an important way. Comments explaining what the code does are often redundant. Comments explaining why — a workaround for a browser bug, a business rule that looks arbitrary, a decision that was deliberately made against the "obvious" approach — are some of the highest-value lines in a codebase.
// Intentionally not using Promise.all here — one slow request
// shouldn't block the others from completing (see incident #482).
const results = await Promise.allSettled(requests);Doesn't hold up: DRY at all costs
Premature abstraction to avoid three lines of duplicated code often creates a worse problem: a shared function that two callers depend on for subtly different reasons, which then needs a boolean flag, then another, until it's harder to read than the duplication would have been. Three similar lines in two places is fine. The rule of thumb: wait for a third occurrence before abstracting, and even then, check whether the two use cases are actually the same concept or just visually similar code.
Holds up: consistent formatting via tooling, not review comments
Bikeshedding over tabs vs. spaces or where braces go is a waste of human review time. Configure Prettier/ESLint (or your language's equivalent) and stop having the conversation. This is one of the highest-leverage, lowest-effort "clean code" wins available — it's a one-time setup cost that removes an entire category of code review friction permanently.
The actual throughline
Every rule above that holds up shares one property: it optimizes for the next person who reads the code, who is very often you in six months with no memory of why you did something. Every rule that doesn't hold up is one that optimizes for an aesthetic ideal instead of that reader's actual experience.
