Naming is treated as the trivial part of programming — the thing you settle quickly so the real work can start. It is closer to the opposite: a name is the interface between what the code does and what the next person believes it does.

When those two diverge, every subsequent decision is made on a slightly false premise.

Wrong names cause real bugs

A function called `validateUser` that also creates a session will eventually be called by someone who wanted validation. A field called `total` that excludes tax will eventually be displayed as a total.

These are not stylistic complaints. They are defects waiting for a reader who trusted the name instead of reading the implementation, which is what names exist to allow.

Difficulty naming is a design signal

When something resists a clear name, it usually does more than one thing. `processOrderAndNotify` is describing a design problem rather than suffering a vocabulary problem.

Treat the struggle as information. Splitting the thing until each part has an obvious name generally produces a better structure than persevering with a compound name.

Use the language of the business

Where the business says shipment, the code should say shipment — not delivery, consignment, and dispatch in three different modules. Translation between vocabularies is a permanent tax on everyone who works across both.

Where the business uses a term inconsistently, that is worth resolving with them rather than encoding the ambiguity.

Rename when understanding changes

Names are chosen when a thing is least understood, and understanding improves. A name that no longer describes what something does should be changed, and modern tooling makes that cheap and safe.

The reluctance is usually social — renaming feels like criticism of whoever chose it. It is worth normalising as ordinary maintenance.

Names are the documentation that cannot be skipped, because they are read every single time the code is. That makes the few minutes spent choosing one an unusually good investment.

Written by the Global IT Solutions engineering team. Have a project this touches on?

Start a conversation