| name | naming |
| description | Evaluate and improve names in code using naming as a design diagnostic. Use when the user asks to "name this", "rename", "review naming", "what should I call", struggles to name something, or when a code review surfaces vague or misleading names. |
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.
- Understandability, Describe the context it represents. A reader should know what it does without reading the implementation
- Conciseness, Use only the words necessary. Longer is not clearer if the extra words add no meaning
- Consistency, Same word means the same thing everywhere. Different things get different names
- 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:
- Read the changed code
- 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?
- Surface violations with specific alternatives
Design Mode
When naming is hard, use the struggle as a diagnostic:
- What does this thing actually do? List its responsibilities
- If the list has more than one item, the naming problem is a design problem, split it
