Naming Things Is the Hard Part. Stop Rushing It.

There's a quote that's been repeated so many times it's become background noise: 'There are only two hard things in computer science — cache invalidation and naming things.' Developers laugh, nod, move on, and then go name a function handleData that processes, validates, transforms, and persists three different types of records. The quote is right. The behavior doesn't change.

Why bad names compound

A bad variable name in one function is a minor annoyance. But names propagate. The poorly-named variable becomes a poorly-named parameter. The poorly-named parameter feeds into a poorly-named function. The poorly-named function gets imported into a component with a misleading prop. By the time someone new opens the codebase, they're reading a system where nothing is called what it actually is, and every piece of understanding has to be earned from scratch instead of gifted by clear names.

What a good name actually does

A good name removes a question. When you read isEligibleForDiscount, you don't need to open the function to know what it returns. When you see fetchUserWithPermissions, you know the difference between it and fetchUser. When a variable is called pendingOrderIds instead of data, you don't need to trace back through three function calls to remember what it contains. Every good name is a piece of documentation that can't go out of date because it lives on the thing itself.

If you need a comment to explain what a variable is, the variable has the wrong name.

— Zaid Maraqa

The rush that causes it

Bad names almost always come from the same place: you know what the thing is right now, while you're writing it, so the name feels fine. result, temp, data, obj — they all made sense in the moment. The problem is that the moment passes. Context fades. The next person reading the code doesn't have your mental state from last Tuesday. They only have the name. And you gave them nothing.

A simple rule that helps

Before you finalize a name, read it in isolation. Not in context, not with the surrounding code visible — just the name. Does it tell you what the thing is, what it does, or what it contains? If you need the surrounding code to make sense of it, the name isn't pulling its weight. Rename it. It takes thirty seconds. The next developer who reads it will spend thirty seconds less being confused. Over thousands of functions, that compounds into a codebase that people actually want to work in.