Identifiers that don't reveal intent — names like aFunc(), x, theData, temp, or one-letter loop variables that force every reader to reverse-engineer the code's purpose. The name fails to carry meaning, so each reader pays search cost to recover it from surrounding code, comments, or git history.
Names that don't disambiguate scope or domain force the agent to read more code into the context window just to know what a variable holds before each reasoning step. Each ambiguous identifier triggers an extra read; chained edits across a file with ambiguous naming compound this cost without proportional information gain.
Names read as the domain — a function's purpose, a variable's role, a class's responsibility — visible in one glance. Each identifier carries enough information that the reader builds a mental model without searching, and comprehension cost drops to the size of the name itself. The team's cognitive load compounds downward as more readers encounter the canonical names.
Identifiers carry enough information that the agent can reason about each symbol without paying retrieval cost to recover meaning from surrounding context. One token of name resolves the question 'what does this hold?' for the agent; reasoning passes proceed with the symbol's semantics already grounded, dropping per-edit context-window load.
Smellier version
function calc(d, t) {return d * t;}
Fresher version
function distance(speed, time) {return speed * time;}
Every reading is a re-comprehension cost; bugs sneak in because what code does diverges from what its name suggests. Readers carry the wrong mental model into edits and ship the misread as plausible-looking code — confabulation from a stale name. The cost compounds in proportion to how many readers touch the file.
Every reasoning step re-derives meaning from surrounding code; chained edits compound the cost, and hallucinations ship as plausible-looking misreads of what symbols stand for. Without disambiguating context, the agent generates code against a guessed meaning — and the guess matches whatever the embedding for that identifier favors in similar codebases.
Cross-repo greps, commit history, code comments, and string-literal references to the old name silently drift stale — the rename's blast radius reaches PRs the team wasn't planning to read. New readers see the new name; old readers carry the old name in their head, paying knowledge-decay cost to recover the original intent every time they return.
Renames invalidate cached associations — commit history, RAG snippets, embedding indexes, and prior conversation context all carry the old name until they refresh. The agent reading any cached source against the renamed code pays cache-staleness cost: cached retrieval surfaces stale snippets, generated code references the old name, and downstream verification fails until every cache rolls forward.
Reduces onboarding time, accelerates code review, and lets future readers skim instead of decode. The mental effort per identifier drops from name-plus-context-recovery to name-only. Bug investigations stay local to the failing symbol instead of expanding into a search for what every adjacent identifier means.
Every later read resolves to one name; the token cost of recovering meaning drops by the size of the context the agent previously had to load. Reasoning passes shrink because the disambiguating context now lives in the identifier itself; the agent generates code with the symbol's semantics already grounded in the name.
Naming bikeshedding — endless rename churn for marginal clarity gains while the actual code structure stays unimproved. Each rebrand invalidates the team's accumulated reading fluency; reviewers spend the rename's blast radius on cosmetic deltas instead of substantive review, and the leaky abstraction underneath the names stays unaddressed.
Renaming every variable whose current name another reviewer would also accept invalidates cached associations across RAG indexes, prior conversation context, and old-name references in code comments — without changing what the symbol stands for. The agent pays full cache-staleness cost across every retrieval surface; the cost-benefit ratio inverts when the old name was already clear enough.