How to Write Understandable Code
Episode 2: Clear Naming Conventions
(Last Updated: 2025.4.4)
Understandable Code
This article takes only 5 minutes to read!
(If the image looks small, try rotating your phone horizontally)
Names are everything!
The most frequently seen elements in code are names—of functions, variables, classes, parameters, and constants. If these names are unclear, the code becomes instantly harder to understand. On the other hand, appropriate naming can make code self-explanatory, even without comments.
In this article, we’ll explore principles for clear naming, good and bad examples, and guidelines for unifying naming conventions across a team.
[Contents]
Characteristics of Good Names
3 Naming Principles
Naming Patterns to Avoid
Guidelines for Consistent Naming
Summary
1. Characteristics of Good Variable, Function, and Class Names
Good names have the following traits:
Immediately convey their purpose
Clearly understood without guessing
Avoid misinterpretation
In short, the most important thing is that *anyone* can instantly grasp the meaning of a name.
2. 3 Naming Principles
There are three principles of naming: Consistency, Intent Revelation, and Appropriate Length.
Consistency means using the same pattern for the same meaning or usage.
See the bad and good examples below—the latter follows consistent rules.
Consistency (C++)
Next is intent revelation. The first example has a variable `d` that gives no clue to its meaning. In contrast, the next example clearly represents “number of days in a year.”
Intent (C++)
Lastly, use appropriate length. For short-lived loop counters, `i` or `j` is fine. But for broader-scope or important variables, use full descriptive names to avoid ambiguity.
3. Naming Patterns to Avoid
Avoid names like the following. While tempting to use names like `flag`, `tmp`, `data`, or `calc`, you should instead choose descriptive names like `consumptionTaxCalc` to make the code meaningful.
Name Issue
tmp, data, value Too vague, unclear purpose
flag1, flag2 Unclear what the flags represent
doIt(), handle() Too generic, lacks specificity
calc() Unclear what is being calculated (e.g., use calcTotal or calcTax)
a, b, c Meaningless in wide scopes
Below are bad and improved naming examples. Compare `flag` with `isConnected`—the latter is much clearer. `calculateTotalPayment` may be longer but explicitly conveys its purpose.
Purpose Bad Example Good Example
Hold user’s age a userAge
Return total payment calc() calculateTotalPayment()
Temporary buffer tmp tempBuffer
Flag flag1 isConnected
4. Guidelines for Unifying Naming Conventions
To maintain consistency, document naming rules at the team or project level. Create coding standards and require adherence.
Unify CamelCase or snake_case
C++ → camelCase / PascalCase
Start function names with verbs
getUserName(), sendMessage()
Use prefixes for booleans: is, has, can
isActive, hasError, canRetry
Use ALL_CAPS with underscores for constants
MAX_BUFFER_SIZE
5. Summary
This article covered clear naming conventions. We’ve seen that names are the most essential factor in conveying the functionality and intent of code.
Use consistent, descriptive, and appropriately long names. Avoid vague or generic names. Formalize naming rules in a coding standard and enforce them through reviews or linters.
With these practices, your code will become clearer and more maintainable over time.
▼References
"Readable Code" by Dustin Boswell & Trevor Foucher, translated by Masanori Kado, published by O’Reilly Japan
