Naming

A name is a tiny abstraction. A good name creates a precise, accurate image of the thing it refers to and quietly excludes what it is not. Names should be precise enough that a reader rarely has to look at the implementation, and consistent enough that the same word always means the same thing.

Why it Matters

Names are read far more often than they are written and are the most frequent interface a reader meets. A precise name lets someone understand code without reading how it works; an imprecise one seeds a wrong mental model that surfaces later as a bug. Naming is where clarity is cheapest to add and most expensive to retrofit.

Signals

• You can describe what a name refers to in a short, concrete phrase. If you cannot, the design behind it is probably muddled.
• The same concept uses the same word everywhere, and different concepts use different words.
• Generic fillers (data, info, manager, process, temp) signal a name carrying no information.

Benefits

Precise names make code obvious, reduce the need for comments, and surface design problems early: a thing that is hard to name is usually a thing that is poorly defined.

Risks

Names that are too long restate the obvious; names that are too short or generic hide it. Reusing one name for two meanings, or two names for one meaning, splits the reader's model. A misleading name is worse than a vague one, because it actively points the wrong way.

Tensions

Brevity conflicts with precision: a longer name carries more information but costs more to read at every use. The resolution is information density, not length. Name to the reader's need and lean on a small, consistent vocabulary so short names stay unambiguous in context.

Examples

A boolean named flag tells the reader nothing; isComplete names the exact condition. block versus firstFreeBlock trades length for precision. Renaming one concept consistently across a codebase often exposes that two call sites meant different things by the same word.