Names Carry Design Intent
What this concept is
Names are the first design tool. A good name reveals role, unit, scope, and domain meaning. It helps the reader predict behavior before opening the implementation.
Why it matters here
Poor naming multiplies confusion across the whole module. It makes functions look more complex than they are, hides responsibility creep, and encourages explanatory comments that should not have been needed.
Concrete example
def get_them():
...
This tells the reader nothing. Compare:
def load_unpaid_invoices():
...
Now the reader knows action, object, and likely result shape.
Useful naming signals:
- verbs for actions:
load_invoice,validate_token - nouns for things:
invoice,token_store - unit clarity:
timeout_seconds,price_cents - domain language:
cart,shipment,enrollment
Common confusion / misconception
Long names are not automatically better. Names should be as long as needed to remove ambiguity, not padded with noise like Data, Info, Manager, Helper, or Processor when those words add no real precision.
How to use it
Ask of each name:
- Would a new reader know what this represents?
- Is the difference from nearby names meaningful?
- Does the name belong to the problem domain or just to implementation mechanics?
Rename aggressively when the answer is no.
Check yourself
What is the difference between a long name that adds precision and a long name that adds only noise?
Mini drill or application
Take five identifiers from an old file. For each one, rewrite it to make one hidden detail explicit: unit, role, boundary, or domain meaning.