Code is read far more often than it is written. It is read by whoever reviews it, whoever fixes it, whoever adds a feature months later, often the same author who has meanwhile forgotten everything. In this continuous reading, names are the most immediate form of documentation: a good name conveys in an instant what a variable contains or what a function does; a bad name forces you to read the code line by line to reconstruct it.
The name must reveal intent
Compare these two versions of the same line:
d = 86400
SECONDS_IN_A_DAY = 86400
The second needs no comment. A good name answers three questions: what this value represents, why it exists, how it should be used. If a name needs a comment to explain it, the name usually needs changing.
Another example, a function:
def process(items):
return [x for x in items if x.status == "A" and x.balance > 0]
def active_customers_in_credit(customers):
return [c for c in customers if c.is_active() and c.balance > 0]
The logic is identical, but the second version can be understood without knowing what the status code "A" means.
Practical rules
Include units of measure
A variable called timeout might be in seconds or milliseconds, and the difference can cause hard-to-find bugs. timeout_seconds or duration_ms remove the ambiguity. The same goes for currencies, distances, sizes in bytes or kilobytes.
Booleans that read like questions
True/false values should have names that sound like a yes-or-no question: is_valid, has_permissions, can_edit, is_active. Avoid negations: not_disabled forces a mental double negative every time you read it, especially in expressions like if not not_disabled.
Functions with a verb
Functions perform actions, so their name usually starts with a verb: calculate_total, send_notification, load_configuration. Functions returning a boolean follow the question rule: is_expired(subscription).
Length proportional to scope
An index in a three-line loop can be called i without any problem: the context is all there, visible. A variable used throughout a module, on the other hand, deserves a full, descriptive name. The rule: the wider the scope, the more explicit the name must be.
A consistent vocabulary
If one part of the code uses fetch_user, another get_customer and elsewhere load_account for equivalent operations, readers will wonder whether there are differences. Choose one term for each concept and use it everywhere. This also applies to domain concepts: if the business talks about "cases", the code should not talk about "tickets".
Frequent mistakes
| Weak name | Problem | Alternative |
|---|---|---|
data |
Too generic, says nothing about the contents | orders_this_month |
temp, tmp |
Does not explain the value's role | price_before_vat |
user_list (which is a set) |
The name lies about the type | users |
handler, manager |
Says little about the responsibility | shipment_scheduler |
x1, x2 |
No meaning | initial_price, final_price |
flag |
Does not say what it indicates | requires_approval |
The case of the name that "lies" is the most insidious: a variable called active_users that actually also contains suspended users leads to wrong decisions by anyone who trusts the name. When a value's meaning changes, the name must be updated.
Language conventions
Every language has writing conventions worth respecting, because they make the code familiar to anyone who knows them:
- in Python,
snake_casefor variables and functions,PascalCasefor classes,UPPER_CASE_WITH_UNDERSCORESfor constants; - in JavaScript and Java,
camelCasefor variables and functions,PascalCasefor classes.
Another decision to make at team level is the language of the names. Many projects choose English, which fits with the language keywords and libraries; others use their local language for domain concepts, because it matches the customers' vocabulary more closely. Both choices are legitimate; random mixing, such as an Italian-English getCliente next to fetch_customer, is not.
Renaming without fear
A bad name is not a life sentence. Modern editors offer automatic rename features that safely update every occurrence, and a good test suite confirms that nothing broke. In my work, when I return to some code and take more than a few seconds to understand what a variable represents, I rename it straight away: it is one of the cheapest refactorings with the highest return.
In short
- Names are the most-read documentation: they must reveal what a value represents and why it exists.
- Include units of measure and give booleans the form of a question.
- Use verbs for functions and names that are more explicit the wider their scope.
- Keep a consistent vocabulary and follow the language's conventions.
- Rename as soon as a name is no longer clear or no longer matches its contents.
