A good name is the cheapest comment you will ever write

Somewhere in the code you wrote last year there is a variable called data. Next to it, quite possibly, there is one called data2. I am not judging. I have written both. But I want to talk about the quiet, compounding cost of the careless name, because it is the cheapest thing in programming to fix and the most expensive thing to leave alone.

The name is read far more often than it is written

You write a name once. After that it is read: by the next person, by the reviewer, by the tool that completes it for you as you type, and above all by you in six months, arriving back at this file with no memory of what you were thinking. A name is not a label you stick on at the end. It is the single most repeated piece of documentation in the whole program, and unlike a comment, it can never drift out of date, because it is the thing itself.

So the question is not whether a name is correct. It is whether a tired person, reading quickly, at the end of a long day, will understand it without stopping. That is a much higher bar than correct.

Every vague name is a decision the author made and quietly declined to write down.

Vague names hide the decision

When I find a function called process, I know almost nothing, and worse, I suspect the author knew almost nothing either at the moment they named it. Process what. Into what. A good name is forced honesty. The instant you try to call it validateAndTrimUserInput, you have to admit that the function is doing three things, and that admission is the first step towards it doing one.

This is why I distrust names that could belong to anything at all. helper, manager, util, handle. They are not really names. They are the places we put things when we have not yet decided what the thing is. A file called utils is a small confession that a shape exists in your program that nobody has been brave enough to name.

The rename is not cosmetic

People treat renaming as tidying, the sort of thing you do if there is time, which there never is. I think that is exactly backwards. When you cannot find a good name for something, that is not a naming problem. That is the code telling you the thing is badly shaped. A concept that resists a clear name is usually two concepts wearing one coat.

So I use the difficulty of naming as a design tool. If a name comes easily, the boundary is probably in the right place. If I sit there stuck, offering myself doThing and manager and other small surrenders, I stop trying to name it and start trying to split it. Nine times out of ten the good names appear the moment the shape is right.

None of this needs a framework or a style guide. It needs about ten extra seconds at the moment of writing, and the willingness to go back and change a name the instant a better one occurs to you. Do that consistently and you will write less documentation, not more, because the code will have started explaining itself. The best comment is the one you never had to write, because the name already said it.