Naming Things Without Pain We've all been there: staring at a variable called or a function called and wondering what the original author was thinking.
Naming is one of the hardest parts of programming, but it doesn't have to be a constant source of frustration.
Here's a practical approach I've refined over years of writing and reviewing code.
1.
Name for the Reader, Not the Writer When you name something, you're writing a tiny piece of documentation.
The reader is usually your future self, six months from now, or a teammate who's never seen this code.
Ask: "If I read this name in a vacuum, would I know what it does or represents?"
2.
Use Meaningful Distinctions Avoid names that differ only by a number or a vague qualifier. , , , are all red flags.
Instead, be explicit about what's different.
3.
Follow the Principle of Least Surprise A name should not mislead.
If a function is called , it should return a user, not update one.
If a variable is called , it should be a boolean.
Consistency with language conventions matters too: in most languages, or prefixes imply a boolean.
4.
Use the Right Level of Abstraction Names should reflect the level of abstraction you're working at.
In a low-level utility, is fine.
In a business logic layer, is better than .
Don't over-abstract either: or are rarely useful.
5.
Avoid Disinformation Don't use names that are easily confused with each other or with built-in keywords.
For example, and are too close, especially in large codebases.
Also avoid using as a variable name in Python because it shadows the built-in type.
6.
Use Pronounceable and Searchable Names If you can't say it out loud, it's hard to discuss in code review. (generation date, year, month, day, hour, minute, second) is a classic anti-pattern.
Also, names like are hard to search for because they appear everywhere.
Use names that you can grep for uniquely.
7.
Use One Word per Concept Pick a vocabulary and stick to it.
If you use , , and interchangeably, readers will wonder if there's a subtle difference.
Choose one word for each concept and use it consistently across your codebase.
8.
For Booleans, Use Positive Names When Possible Negative names like or are harder to read in conditions.
Prefer positive ones and use when you need negation.
9.
Don't Be Afraid to Rename If you notice a bad name during code review, fix it.
If you're refactoring and a name no longer fits, change it.
Modern IDEs make renaming safe and fast.
Leaving a bad name because "it's already there" accumulates technical debt.
10.
When in Doubt, Ask If you're unsure what to name something, ask a teammate or write a comment explaining what it does.
Sometimes the act of describing it helps you find the right name.
You can also use a placeholder like but don't leave it forever.
A Simple Heuristic If you can't come up with a good name within a few minutes, you might not understand the problem well enough.
Step back and revisit what the function or variable really does.
Often, a good name emerges once you clarify the intent.
Naming is a skill, not a talent.
With practice and intentionality, you can write code that reads like a well-structured story.
Your future self will thank you.
For more on this topic, check out the classic book Clean Code by Robert C.
Martin, which has an entire chapter on meaningful names.
Also, the Google Style Guides offer language-specific naming conventions that are worth following.