A Good Name Removes The Need For A Comment

When you find yourself explaining what something is, check whether the name could have said it instead.

There is a reliable signal available to anyone willing to notice it. If you write a line of explanation immediately above something, and that explanation is describing what the thing is or what it holds, the name has failed and the comment is patching the failure. The patch is worse than the fix. A name travels with the thing everywhere it is used, into every call site and every search result and every error message. A comment sits in one place and rots there, because nothing forces it to change when the code beneath it does. Fixing the name is a permanent improvement. Adding the comment is a temporary one that decays without announcing that it has decayed.

The habit that follows is small and slightly tedious: when you reach for an explanatory comment, spend thirty seconds trying to fold it into the name first. Often the comment contains exactly the words the name was missing. It says which units the number is in, or which of two possible states the flag represents, or that the collection is ordered, or that the value has already been validated. Any of those can usually live in the name. Length is not the enemy. A long name that is read correctly on the first pass is cheaper than a short one that sends the reader hunting through three other places to work out what it means.

There are limits and it is worth being honest about them. Some things genuinely cannot be named into clarity, because the concept itself is unfamiliar, or because it belongs to a business domain with its own vocabulary that no name will teach you. In those cases the comment is doing real work and should stay. But that case is much rarer than the volume of explanatory comments in most systems would suggest. The majority are not conveying domain knowledge. They are apologising for a name chosen quickly, kept out of momentum, and never revisited because renaming felt like churn rather than repair.