On naming variables

19 Sep, 2025

Three rules prevent a lot of trouble:

1. Call it what it is, not what it does.

When you want to talk about a pepperoni pizza, you call it a pepperoni pizza. Even if you order a pepperoni pizza every Wednesday and only on Wednesdays, so that your Wednesday dinners are exactly your pepperoni pizzas, you would still order a pepperoni pizza, not an "every-Wednesday-dinner."

Why is this better?

• Your listeners don't have to remember your eating habits to know what you're talking about.
• Your dinner habits might change. If you call a pizza a pizza, and not a Wednesday-dinner-thing, you don't have to reform your language along with your dinner plans.
• Readers and listeners expect things to be called according to their essences. This expectation is tacit and defeasible, but very real. Without this shared understanding, it would be vastly harder for language to turn into understanding.

So, when you're naming variables:

• If a parsed server response represents a set of pizza toppings, call the variable pizzaToppings, not parsedServerResponse. (But if the response is still in some raw, untrusted state, so that it really is more of a server response than a set of pizza toppings, then go ahead and call it serverResponse.)
• If you're using the color of a button to indicate danger, call the variable holding the color buttonColor, not dangerIndicator.

2. Don't use synonyms or near-synonyms just to have different names.

When a news article uses said, stated, affirmed, and many more synonyms in a single article, readers aren't charmed or refreshed; they're just annoyed. Repetition does bother us, but varying the words without varying their meanings adds new annoyances far more effectively than it relieves the annoyance of repetition.

Using synonyms is even worse in code: it still annoys the reader, but also involves a sort of lie. In code, variables with different names are different variables that the reader has to distinguish. By naming them synonymously, you're telling the reader that they are the same, but they're not.

Don't do this! Instead, figure out why you're doing this. Some common reasons are:

a. You have messy, disorganized blobs of data, each of which has to do with X. You're using two of your X-blobs in the same scope, but you can't name them both X. E.g.:

const { hat } = useHatContext();
const chapeau = await gnarlyAPIResponse.then(fourHundredLineTransformationFunction);

b. You are representing the same real-world thing in different ways: a hat as an inventory item usually needs a different representation from a hat in a checkout flow. (The idea of a bounded context can be useful here.)

c. You are storing the results of an intermediate computation for expedience:

const hats = await gnarlyAPIResponse.then(fourHundredLineTransformationFunction);
const theHats = hats.map(
	(hat) => {name: hat.name, coolness: coolnessMetricCalculatorFor(hat)}
); // You still need hats but want to pass around this smaller array

Try to address the underlying problem instead of using a synonym. Note, though, that sometimes fixing these problems can require nontrivial refactors. If you just can't fix the underlying problem immediately, you might need some combination of humility, and your code reviewers might need to be satisfied with progress (not perfection).

3. Don't put the data type in the variable.

Your readers should already know the data type, especially if it's important. If it's important and your programming language doesn't require you to make it explicit, use some other mechanism (e.g., Python type hinting) than putting the type in the name. Here are some common reasons for names like hatList or hatSizeAsDouble:

a. There's already a variable called (e.g.) hats, and the programmer needed a different one for hatList. See (2) above. b. It's really important that, e.g., hatSizeAsDouble is a Double and not a Long. In this case, say why in a comment, not in the name. (Also, if that's true, something dangerous is probably happening. Please test for all the possible dangerous cases, if you really can't avoid it.) c. It's been a long time since hatList was declared as a List. A function is probably too long, too complex, or both. Even if you can't fix this now and really must remind your reader of the data type, comments are a better solution.

Happy coding, and happy variable naming! Call your variables precisely what they are, and you can't go far wrong. As always, remember John Ousterhout's wise guidance (in this book): "If it’s hard to find a simple name for a variable or method that creates a clear image of the underlying object, that’s a hint that the underlying object may not have a clean design."