Naming

Naming as Design

Overview

Naming difficulty is a design smell. When you struggle to name something, the abstraction is wrong. Use naming as a lens to surface confused boundaries, mixed responsibilities, and domain misunderstanding.

Benner's Four Principles

Every name balances four properties. When they conflict, make the tradeoff deliberate.

1. Understandability — Describe the context it represents. A reader should know what it does without reading the implementation
2. Conciseness — Use only the words necessary. Longer is not clearer if the extra words add no meaning
3. Consistency — Same word means the same thing everywhere. Different things get different names
4. Distinguishability — A name must be distinct from its neighbors. Similar names for different things cause bugs

See references/principles.md for detailed rules and naming smells.

Two Modes

Review Mode

Examine names in recently changed code:

1. Read the changed code
2. For each name, ask:
   • Does it pass all four principles?
   • Could a reader understand this without context?
   • Is the verb specific? ("process", "handle", "manage" almost never are)
   • Does it match the domain language?
3. Surface violations with specific alternatives

Design Mode

When naming is hard, use the struggle as a diagnostic:

1. What does this thing actually do? List its responsibilities
2. If the list has more than one item, the naming problem is a design problem — split it
3. Who calls it? What do they expect?
4. If it disappeared, what would break? That's what it is
5. What would the domain expert call it?

Naming Smells

Names that signal design confusion:

Bloch's API Design Maxims

For public interfaces — APIs, library boundaries, module exports:

• Names should be self-documenting. If you need a comment to explain what a function does, rename it
• Same word, same meaning. Don't use "remove" in one place and "delete" in another for the same operation
• Principle of Least Astonishment. A method named check should not modify state
• If it's hard to name, the design is wrong. Rename the design, not just the symbol

Evans' Ubiquitous Language

Code names should match how domain experts talk:

• If the business says "order" and code says "purchase", one of them is wrong
• Naming mismatches between code and conversation reveal domain misunderstanding
• When renaming, update tests, docs, and conversations — not just code

Naming Checklist

For any name under review:

[ ] Specific verb (not handle/process/manage/do)
[ ] No unnecessary words
[ ] Consistent with similar names nearby
[ ] Distinguishable from neighbors
[ ] Matches domain language
[ ] Readable without implementation context
[ ] No embedded type information
[ ] Boolean reads as a question (isReady, hasPermission, canEdit)

Output Format

When reviewing names:

## Naming Review

### Must Rename

- `processData` → `validateInvoiceLineItems` — "process" hides
  the actual responsibility; this only validates
- `handleClick` → `submitPayment` — name the action, not
  the event

### Consider Renaming

- `userInfo` → `billingProfile` — more specific to its
  actual contents

### Design Concern

- `OrderManager` has 12 methods spanning validation,
  persistence, and notification. The naming struggle
  reflects three responsibilities that should be separate
  types.

Before/After Examples

Functions

Variables

Types and Modules

Booleans

Strunk's Rule 12

"Use definite, specific, concrete language." The prose skill teaches this for English. Apply it identically to code:

See Also

• /design — Hard-to-name things signal design problems
• /review — Code review surfaces naming issues; naming review deepens code review
• /prose — Strunk's rules apply to code names identically to English prose
• skills/FRAMEWORKS.md — Full framework index

Converted and distributed by TomeVault — claim your Tome and manage your conversions.