tslateman/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:

| Smell | Example | What it reveals | | -------------------------------------- | ------------------------------ | ------------------------------------- | | Generic verb | handleData, processRequest | Unclear responsibility | | Suffix -Manager, -Helper, -Utils | UserManager, StringHelper | God object or junk drawer | | And/Or in name | validateAndSave | Two responsibilities | | Type in name | userList, nameString | Redundant or wrong abstraction level | | Negated boolean | isNotReady, disableFeature | Double negatives in conditions | | Abbreviated beyond recognition | usrSvcRsp | Conciseness without understandability |

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

| Before | After | Why | | -------------------- | ----------------------------------- | -------------------------------------------------------------- | | processData(input) | validateInvoiceLineItems(invoice) | "Process" hides responsibility; name the action and the domain | | handleClick() | submitPayment() | Name the business action, not the DOM event | | doStuff(items) | deduplicateContacts(contacts) | Eliminate weasel verbs; name what it actually does | | run() | pollForStatusUpdates() | Ambiguous in any class with more than one operation |

Variables

| Before | After | Why | | -------- | --------------------- | --------------------------------------------------- | | data | unpaidInvoices | Generic noun → specific domain concept | | temp | unsavedDraft | Reveals intent; "temp" says nothing about lifecycle | | flag | requiresApproval | Reads as a question; boolean purpose is clear | | result | validationErrors | Names the content, not the role in the function | | list | activeSubscriptions | Type-in-name smell; name the contents instead |

Types and Modules

| Before | After | Why | | --------------- | --------------------------------- | -------------------------------------------------------- | | UserManager | UserRepository + UserNotifier | -Manager reveals multiple responsibilities; split them | | StringHelper | SlugFormatter | -Helper is a junk drawer; name the actual capability | | DataService | InventoryClient | Two generic words; name the domain and the role | | utils/misc.ts | pricing/discount-rules.ts | File path is a name too; make it navigable |

Booleans

| Before | After | Why | | ---------------- | ------------------------------- | ------------------------------------------------ | | isNotReady | isReady (invert usage) | Avoid double negatives in conditionals | | disableFeature | featureEnabled (invert usage) | Positive form reads naturally in if statements | | check | hasPermission | "Check" doesn't say what the answer means |

Strunk's Rule 12

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

| Vague | Specific | | --------- | ------------------ | | getData | fetchUserProfile | | item | cartLineItem | | result | validationErrors | | info | shippingAddress | | temp | unsavedDraft |

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