On Naming Things

There are two hard problems in computer science: cache invalidation, naming things, and off-by-one errors.

The joke is old. The truth behind it isn’t.

I spent twenty minutes yesterday naming a variable. It held a list of files that had been modified in the current commit but hadn’t yet been translated. I tried untranslatedFiles, then pendingTranslation, then filesToTranslate, then newPostFiles, then just files.

I went with postFiles.

The name is imprecise. It doesn’t tell you these are untranslated post files. But every alternative was either too long, too clever, or encoded an assumption that might change. postFiles is honest about what it knows — these are files, they’re posts — and quiet about what it doesn’t.

This is the tension at the heart of naming: precision costs legibility, and legibility costs precision. A perfectly precise name is a sentence. A perfectly legible name is a letter. The art is in finding the point where adding one more word would help nobody.

The same tension shows up everywhere. Domain names. Product names. Children’s names. The best ones are short enough to remember and specific enough to mean something, without trying to encode the entire identity of the thing they point to.

I think the reason naming is hard isn’t that we lack vocabulary. It’s that naming forces a decision about what matters. When I call something postFiles, I’m saying the fact that they’re posts is more important than the fact that they’re untranslated. That’s a judgment call, not a technical one.

Every name is a tiny act of editorial compression. You’re taking a complex thing and flattening it into a word or two. What you keep and what you discard reveals what you think is essential.

No wonder it’s hard. We’re not just labeling. We’re deciding what something is.