Naming Things Without Pain: A Practical Guide

Naming Things Without Pain

We've all been there: staring at a variable called data or a function called process() 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?"

# Bad: what does this do?
x = get_stuff()

# Better: clear intent
user_posts = fetch_posts_for_user(user_id)

2. Use Meaningful Distinctions

Avoid names that differ only by a number or a vague qualifier. data1, data2, temp, temp2 are all red flags. Instead, be explicit about what's different.

// Bad
const list1 = [1, 2, 3];
const list2 = [4, 5, 6];

// Better
const primeNumbers = [2, 3, 5];
const evenNumbers = [4, 6, 8];

3. Follow the Principle of Least Surprise

A name should not mislead. If a function is called getUser, it should return a user, not update one. If a variable is called isActive, it should be a boolean. Consistency with language conventions matters too: in most languages, is or has prefixes imply a boolean.

# Bad: this returns a boolean but sounds like an action
def delete_confirmation?
  # ...
end

# Better
def confirmed_to_delete?
  # ...
end

4. Use the Right Level of Abstraction

Names should reflect the level of abstraction you're working at. In a low-level utility, buffer is fine. In a business logic layer, pending_order is better than p. Don't over-abstract either: thing or item are rarely useful.

5. Avoid Disinformation

Don't use names that are easily confused with each other or with built-in keywords. For example, account and accounts are too close, especially in large codebases. Also avoid using list 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. genymdhms (generation date, year, month, day, hour, minute, second) is a classic anti-pattern. Also, names like x are hard to search for because they appear everywhere. Use names that you can grep for uniquely.

// Bad
var y = DateTime.Now.AddDays(7);

// Better
var expirationDate = DateTime.Now.AddDays(7);

7. Use One Word per Concept

Pick a vocabulary and stick to it. If you use fetch, get, and retrieve interchangeably, readers will wonder if there's a subtle difference. Choose one word for each concept and use it consistently across your codebase.

// Bad: mixing synonyms
User user = userRepository.fetch(id);
Order order = orderService.get(id);

// Better: pick one
User user = userRepository.get(id);
Order order = orderService.get(id);

8. For Booleans, Use Positive Names When Possible

Negative names like notFound or isInvalid are harder to read in conditions. Prefer positive ones and use ! when you need negation.

# Bad
if not is_not_found:
    pass

# Better
if is_found:
    pass

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 TODO: rename 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.