The Cost of a Mess, and Names That Pay Rent
Messy code is not ugly, it is slow — and the cheapest way to buy the speed back is to make every name tell the truth.
The idea
Nobody pays you to write pretty code. But every team learns the same lesson eventually: a mess makes the next change slower, and the one after that slower still. That is compound interest working against you, not an aesthetic complaint. This module starts by making you feel the tax with a stopwatch, because a number you measured on your own machine is more convincing than any chapter.
Everyone plans to clean up once things calm down. Things never calm down. The only cleanup that actually happens is the kind woven into normal work — leave every file a little cleaner than you found it. A rename here, a dead variable deleted there.
Names are the cheapest, highest-leverage cleanup there is. A rename changes no logic and risks almost nothing, yet reading code is mostly answering the question "what is this thing?" over and over. A good name answers instantly. A bad name sends you off to find where it was assigned, every single time.
Concretely, a good name says why the thing exists, what it does, and how it is used, without a comment. The rest of the rules are about not lying and not making the reader work: no names that disinform, no noise words that create fake distinctions, no unsearchable magic numbers, classes as nouns and methods as verbs, and one word per concept across the whole codebase. Throughout, the code keeps working — you change structure, never behavior.
The bench — 3 exercises
The Scavenger Hunt
Time yourself answering five "where does X happen?" questions against the untouched messy code, so you have a personal baseline for what bad names cost you.
- Pick five questions about the codebase before you look at it, such as which function decides the bulk discount and where the late-payment penalty rate is set.
- Start a timer, answer each one with a file and line, and record how long each took.
- Save the answers and times to a baseline file you will not touch again for the rest of the track.
- Note which questions you gave up on — a give-up is data about the mess too.
hint
Go in cold. Grepping around beforehand destroys the only measurement you get.
hint
Stuck past five minutes on one question? Record it as a max-time entry and move on.
DONE WHEN
· A baseline file exists with five questions, answers, and elapsed times
· You can state, in seconds, what the slowest lookup cost you
· The baseline is committed and untouched afterwards
The Great Rename
Rename every identifier that hides its meaning and hoist every repeated magic number into a named constant — dozens of edits, zero behavior change.
- List the offenders: single letters outside loop counters, abbreviation soup like genymdhms, noise pairs like productData next to productInfo, Hungarian prefixes like strName, and bare numbers repeated in two or more places.
- Rename each one with your editor's rename-symbol command rather than find-and-replace.
- Replace repeated literals with named constants that would actually turn up in a search.
- Run the full test suite after each batch and confirm it stays green.
- Sweep once more for consistency: pick one of get, fetch, or retrieve for the same idea and use it everywhere.
hint
Can't name something? That is usually the code confessing it does two things. Name the dominant purpose and note the spot — splitting it is the next module's job.
hint
Classes are nouns, methods are verbs. If a name breaks that, it is usually mislabeled.
DONE WHEN
· Test suite is green and the app's output is byte-for-byte identical to before
· No single-letter names remain outside for-loop counters
· No Hungarian prefixes and no noise-word near-duplicates remain
· No bare numeric literal appears in two or more places in domain code
The Disinformation Audit
Hunt down the names that are actively false, not merely vague, and write up what each one lied about — the reflex that transfers straight into code review.
- Find at least five names that assert something untrue: a list that is really a map, an isValid that also mutates and saves, a DAYS_IN_MONTH set to 30, a tmp that is load-bearing state, a customerName holding an id.
- Read the call sites, not the declarations — a lie is visible where the promise meets what callers receive.
- Rename each to the truth, then rerun the tests.
- Write one line per finding in an audit file: old name, new name, what it lied about.
hint
Vague names waste time; lying names cause bugs, because readers trust names and skip the code behind them.
hint
If the truthful name feels embarrassingly long, the thing itself probably needs splitting later — record it and move on.
DONE WHEN
· At least five lying names renamed, none of them still implying the wrong type or effect
· Audit file has one entry per finding with the lie stated
· Tests still green after every rename
Go deeper (after the bench)
Read Clean Code chapters 1 and 2 now that you have felt the argument — chapter 1's interviews with Beck, Cunningham and Stroustrup on what "clean" means to each are worth the detour. If a good name still won't come, work through Arlo Belshee's free "Naming as a Process" series at arlobelshee.com, a seven-step ladder from placeholder names to intention-revealing ones.