Names and readability

Several books and studies discuss what "good names" are. This article organizes facts from Clean Code, Code Complete, Mythical Man-Month, and Cognitive Load theory.

1. Where names land

Names are the surface that lands first in the head of a person reading code. With precise names, intent comes through even when half the body is left unread; with blurry names, intent stays blurry even after reading the whole body.

2. Clean Code (Martin, 2008)

Rules from chapter 2 "Meaningful Names" (abridged):

• Use Intention-Revealing Names — show intent like daysSinceCreation instead of d.
• Avoid Disinformation — avoid names whose connotations differ from reality (accountList shouldn't be used unless it really is a List).
• Make Meaningful Distinctions — avoid meaningless distinctions like a1, a2, a3 and noise words like Info / Data.
• Use Pronounceable Names — pronounceable names make discussion easier.
• Use Searchable Names — single-letter variables are hard to search.
• Class Names — nouns. Method Names — verbs.
• One Word per Concept — one word per concept (don't mix get / fetch / retrieve for the same meaning).

3. Code Complete (McConnell, 2004)

Guidance from chapter 11 "The Power of Variable Names" (abridged):

• Length of the name is proportional to the scope of influence. The loop index i can be short, but a module-global constant should be long.
• The optimal variable name length is 9 to 15 characters, citing internal research (IBM and others). The range that's neither too short nor too long.
• The name says what it refers to; if possible, leave out how it's implemented.
• Negative names (isNotFound) confuse in double negation.

4. Essential vs accidental complexity

Frederick P. Brooks Jr.'s No Silver Bullet (1986, later included in the 1995 edition of The Mythical Man-Month) distinguishes two kinds of complexity:

• Essential complexity — complexity intrinsic to the problem itself. Business domain rules, regulations, physical constraints. Cannot be reduced.
• Accidental complexity — complexity added by tools, languages, and implementation choices. Can be reduced with better abstractions, names, and structure.

Good names are among the cheapest ways to reduce accidental complexity. It's common to see one renamed identifier remove five lines of comments.

Brooks's central claim is that tooling improvements have greatly lowered accidental complexity but essential complexity remains, so no single tool can raise productivity by an order of magnitude ("there is no silver bullet"). Names work the same way: good names don't eliminate essential complexity, but they reduce accidental complexity, making time to engage with what's essential.

5. Cognitive load theory

A learning theory John Sweller organized in his 1988 paper Cognitive load during problem solving. The frame: limits of working memory affect learning and problem solving.

Classification:

• Intrinsic load — difficulty of the material itself. (≈ essential complexity)
• Extraneous load — burden added by how the material is presented. (≈ accidental complexity)
• Germane load — active cognitive activity that leads to learning.

Reading code can be explained with the same model. Books like Programmer's Brain (Felienne Hermans, 2021) apply this theory to code readability. The view is that blurry names, repeated magic numbers, and inconsistent style add extraneous load.

6. Common heuristics

• One meaning per name — don't call the same concept differently in two places.
• Can a stranger guess its meaning in 5 seconds? — if not, rename it.
• Booleans in question form — isReady, hasError.
• Function names reveal side effects — pure transformations get noun-like names (toUpper); state changes get verb forms (saveUser).
• Convention consistency — follow the language/team standard for camelCase / snake_case / PascalCase, and don't mix them within one repo.

7. When short names are appropriate

Longer names are not always better. Cases where short names fit:

• Temporary variables in narrow scopes (short lambdas, small helpers).
• Domains with established mathematical conventions (x, y, z, dx, dy).
• Standard library conventions (i, j indices).

McConnell's "proportional to scope of influence" also justifies short names in that direction.

8. Common pitfalls

Noise words — Manager, Helper, Util, Data, Info blur meaning when piled up. Adding one more word to say what the class is is clearer.

Hungarian notation — embedding type in the name (strName, iCount) hurts readability since strongly typed languages became common — a settled view.

Abbreviations — domain-standard abbreviations (http, url) are fine, but team-only abbreviations (accInf) burden new members.

Negation of negation — expressions like if (!isNotEmpty). Switching to a positive name aids readability.

Fear of renaming — IDE safe refactor (rename) has matured enough. The cost of fixing a blurry name in a small PR keeps shrinking.

Closing thoughts

Names are the cheapest tool for reducing accidental complexity. The combination of Clean Code's intention-revealing names + Code Complete's length proportional to scope of influence + reducing extraneous load from cognitive-load theory forms the foundation of good names. In an era when the cost of renaming is low, fix blurry names where you find them.

Next

• (philosophy end)

Robert C. Martin Clean Code · Steve McConnell Code Complete 2nd Edition · Frederick P. Brooks Jr. No Silver Bullet (PDF) · John Sweller Cognitive load during problem solving (1988) · Felienne Hermans The Programmer's Brain · Phil Karlton "two hard things" · Kent C. Dodds Make Impossible States Impossible for reference.