The Quiet Discipline of Naming Things

There’s a famous joke in software: there are only two hard things in computer science, cache invalidation and naming things. People laugh at it but they don’t actually act on it. Most code I read — including code I wrote a year ago — is full of names that are almost right.

processData. handleUser. manager, service, helper. These names tell you nothing. They are placeholders that someone forgot to replace.

The reason naming is hard is the same reason writing is hard. To name something well you have to know exactly what it is. Not roughly. Not approximately. Exactly. And most of the time, when you sit down to write a function, you don’t quite know exactly what it is yet — you’re discovering it by writing.

This is fine, except that the discovery doesn’t end when the function compiles. It ends when you can name the function in a way that wouldn’t surprise a stranger reading the call site. If you can’t, you don’t actually know what the function does. You know what it currently happens to do.

The discipline is to keep going. After the function works, after the tests pass, after the PR is open — go back and try one more time to name it. You will almost always find that the name you can write now is more accurate than the name you wrote when you started, because you understand the thing better now than you did then. And the difference between the old name and the new name is the part of the function you didn’t actually understand.

This is also why renaming is so therapeutic. It’s not really about the name. It’s about checking whether your understanding has caught up with your code.