The Particular Damage Done By A Name That Is Nearly Right

An obviously wrong name gets corrected. A slightly wrong one gets believed.

A badly wrong name is a mild problem. Nobody trusts it, everybody checks, and someone eventually fixes it. The dangerous case is the name that is almost accurate: it describes the thing as it was, or as it mostly is, or as it is on the common path. That name gets believed. A reader takes it at face value, reasons from it, and builds a correct chain of logic on a false premise. They do not check, because nothing prompted them to. The bug that results is not a typing mistake, it is a reasoning mistake, and it will be hard to find precisely because the code reads perfectly well to anyone who accepts the name.

The usual origin is drift rather than carelessness. Something is named accurately, then its responsibilities expand a little, then a little more, and at no single point does the change feel large enough to justify a rename. A name that once described one clear thing ends up covering a family of loosely related things, and the reader who assumes the original meaning is wrong in a way nobody has documented. This is why renaming during ordinary work is not cosmetic. It is the maintenance that keeps the vocabulary honest, and skipping it accumulates a debt that is paid at the worst possible moment.

Two questions catch most of these. First: does this name describe what the thing does now, or what it did when someone first wrote it? Second: if a stranger read only the name and never the body, what would they wrongly conclude? The second question is the sharper of the two, because it asks you to model a reader who trusts you. If the honest answer is that they would conclude something false, you have found a defect. It does not look like a defect, it will not appear in any list of open faults, and it will eventually cost somebody a long afternoon.