Choosing Meaningful Variable Names

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.

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.

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.

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.

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.

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.

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.

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.