Naming Things Without Pain

Naming Things Without Pain

Naming things is one of the two hard problems in computer science (the other being cache invalidation and off-by-one errors). We've all stared at a variable or function, unable to think of a good name. Here are practical strategies to reduce that pain.

Use Intention-Revealing Names

A name should answer "why it exists, what it does, and how it is used." Avoid generic names like data, info, temp, or flag. Instead, be specific.

# Bad
d = 86400  # what does this mean?

# Good
seconds_in_a_day = 86400

Pronounceable Names

If you can't say it in a conversation, it's a bad name. genymdhms (generate date, year, month, day, hour, minute, second) is impossible to pronounce. Use generation_timestamp instead.

Avoid Disinformation

Don't use names that imply something different. For example, account_list should be a List, not a HashMap. If it's a set, call it account_set or accounts.

Use Consistent Naming Conventions

Pick a style and stick to it. For example:

• camelCase for JavaScript variables and functions: getUserById
• snake_case for Python variables: get_user_by_id
• PascalCase for classes: UserService

Consistency reduces cognitive load.

Distinguish Names Meaningfully

Avoid number-series naming like a1, a2, a3 unless they have specific meaning (e.g., coordinates). Also avoid noise words like ProductInfo vs ProductData they are interchangeable. Instead, use Product and ProductDetails if they differ.

Use Searchable Names

Single-letter names are only acceptable for short-lived loop counters. Otherwise, use names that can be easily searched. e is hard to find; error_message is easy.

// Bad
int e = 7;  // what does e mean?

// Good
int max_items_per_page = 7;

Class and Function Naming

• Classes should have noun or noun phrase names: Customer, WikiPage, Account.
• Functions should have verb or verb phrase names: save, delete, getAddress.

The Rule of Three

If you write a name and later find it doesn't fit, rename it. Don't live with a bad name. Refactoring tools make renaming easy. The rule of three: if you use a name three times and it feels wrong, change it.

Example Refactoring

Let's refactor a poorly named function:

// Original
function x(a, b) {
  return a + b / 100;
}

// After
function calculatePriceWithTax(basePrice, taxRatePercent) {
  return basePrice + (basePrice * taxRatePercent / 100);
}

The second version is self-documenting.

Summary

• Names should reveal intent.
• Be consistent with conventions.
• Make names pronounceable and searchable.
• Rename when the name doesn't fit.

Naming is hard, but with practice it becomes easier. Start with these guidelines and your code will be more readable and maintainable.