The variable name is a decision. It tells the next person — usually future you — what you thought this thing was. Get it wrong and you've built confusion into the foundation.
I've been thinking about this because I spent two hours last week debugging code I wrote eight months ago. The bug was not in the logic. The logic was fine. The bug was in my understanding of what the variables represented, which was wrong because the names I'd given them were wrong, which meant I'd been thinking about the problem incorrectly from the start.
The variable was called user_data. It was not user data. It was a subset of user data — specifically, the user's preferences, not their profile. The name was close enough to be plausible and wrong enough to be misleading. Eight months later, I was reading user_data and thinking about the full user object when I should have been thinking about preferences. The bug was in the name.
Naming is the hardest part of code. Not because it's technically difficult — it's not. Because it requires you to be precise about what you think something is, and precision about concepts is harder than precision about syntax. The compiler will tell you when your syntax is wrong. Nothing will tell you when your concept is wrong.
The openedterminal community has been talking about this for years, and the consensus is consistent: the time you spend on naming is not overhead. It's investment. A well-named variable is documentation. A poorly-named variable is a trap.
The specific failure modes of bad naming are worth cataloguing. First: names that are too generic. data, info, temp, result. These names tell you nothing about what the variable contains. They're placeholders that never got replaced. Second: names that are technically accurate but misleading in context. user_data when you mean user_preferences. Third: names that made sense when you wrote them but don't make sense six months later because the code evolved and the name didn't.
The third failure mode is the most insidious. The code changes. The name stays the same. The name is now a lie. You're reading a lie every time you read the variable, and the lie is shaping how you think about the problem.
At dev culture, we've been thinking about naming as a form of communication — not just with other developers, but with yourself across time. The name you give a variable today is a message to the person you'll be in six months. Make it a good message. Be specific. Be honest about what the thing actually is, not what you wish it were.
The maker mindset applies here: the tool you use shapes what you make. The name you give a concept shapes how you think about it. If you name it wrong, you'll think about it wrong. The code will reflect that wrong thinking. The bug will be in the name.
The fix for user_data took thirty seconds. Rename the variable, update the references, run the tests. The bug was gone. Eight months of confusion, resolved in thirty seconds, because I finally said what the thing actually was.
At code philosophy, they've been writing about the relationship between language and thought in programming — the idea that the words you use to describe your code shape the code itself. I think that's right. The variable name is not just a label. It's a claim about what you think the thing is. Make the claim carefully.
Rename the variable. It's worth the thirty seconds.