Choosing Meaningful Variable Names

The Reader's Real Question

When you return to your own code months later, or when a teammate reads it for the first time, the important question is usually not what the syntax is doing. The syntax already shows that. The more useful question is why the code is doing it and what the values mean in the problem being solved.

From Vague Names to Clear Meaning

A vague name forces a reader to search elsewhere for meaning. A descriptive name can make the purpose of a value visible without an explanatory comment. The improvement is not that the assignment itself changes; the improvement is that the name communicates what the value represents.

v = 5

velocity = 5

The first name gives little information about the value. The second name tells the reader that the value represents velocity. A name can therefore remove the need for a comment that merely translates an assignment into words.

What Redundant Comments Hide

v = 5  # assign 5 to v

Anyone reading this line can already see that 5 is assigned to v. The comment adds no domain meaning, intent, assumption, or reasoning. It also creates maintenance work: if the code changes, the comment may become inaccurate.

Context the Syntax Cannot Show

A useful comment explains the why. It can describe a value's real-world meaning, its units, an assumption that must remain true, the reason for a design choice, or information from external documentation. These details affect how a reader should use or modify the code, but they are not necessarily visible in the syntax.

velocity = 5  # measured in meters per second

The assignment shows the value being stored, and the variable name shows that it represents velocity. The comment adds the unit: meters per second. That domain information helps a reader use the value correctly, convert it when necessary, and understand comparisons involving it.

The Name-Length Trade-Off

Good variable names reduce the need for comments, but the longest possible name is not always the clearest choice. When several variables have very long names, a calculation can become a wall of text that is difficult to parse visually. In that situation, a shorter name paired with a precise comment may be easier to understand than an extremely long name.

total = subtotal + shipping + tax

# Tax uses the fixed rate assumed for this calculation.
total = subtotal + shipping + tax

In this example, the arithmetic remains easy to scan because the names are concise. The comment contributes the assumption about the tax rate rather than repeating that the values are being added. The goal is balance: make names clear enough to communicate meaning, but do not let names make an expression unnecessarily dense.

A Practical Review Sequence

Mistakes That Reduce Clarity

• Writing a comment that repeats the operation

  The assignment is already clear from the syntax, so the comment adds no new information.

  Fix: Use a meaningful name or explain the domain meaning, unit, assumption, or intent that the syntax cannot show.

• Assuming that a longer variable name is always better

  Long names can make the expression visually dense and harder to parse.

  Fix: Balance descriptive names with brevity. When needed, use concise names and a clear comment containing the missing context.

• Leaving a comment unchanged after changing the code

  An outdated comment can actively mislead readers about the current behavior or meaning of the code.

  Fix: Review comments whenever the related code changes and remove or update comments that no longer match.

• Using a comment instead of improving an unclear name

  A comment may explain a vague name temporarily, but the name itself still fails to communicate meaning wherever it is used.

  Fix: Prefer a meaningful variable name when the missing information is the value's identity or domain meaning.

Practice the Decision

1. The best answer is not to comment everything or to avoid comments completely. Improve a vague name when the name itself hides meaning. Leave out a comment when the code is already clear. Add a comment when the reader needs domain context, an assumption, a unit, or reasoning that the syntax cannot communicate. If names become so long that an expression is difficult to read, use concise names with a focused, synchronized comment.