A variable name is a small note to the next person reading the code. Sometimes the note says what is inside. Sometimes it says data, which is roughly as helpful as labeling a moving box “objects.”
This field guide uses fictional specimens. None were taken from a private repository, and no real developer is being summoned to explain a Tuesday afternoon decision. The examples use Python-style spelling for consistency. The underlying joke is about missing meaning, not a universal rule that every project should use the same capitalization.
The project-level version of a useful label is a clear delivery claim. These working rules after the AI prototype ask clients and developers to name what was actually checked.
data: the container without a label
data makes a statement that is usually difficult to dispute. The program does contain data. Unfortunately, the reader was hoping to learn something slightly more specific.
In our invented example, the value holds rows that passed an import check. Calling it validated_rows supplies both the kind of thing and a relevant state. The reader no longer has to revisit the previous function merely to discover whether these are raw inputs, rejected records or the survivors.
That does not mean every local name needs a biography. Inside a tiny function whose purpose is obvious, a short generic name can be enough. The problem appears when the label travels farther than its context. A box marked “objects” is manageable while you are packing it. Six months later in a storage unit, the label has become a practical joke.
temp2: the temporary resident
temp2 tells a story about the author’s process. There was a first temporary thing. Then another thing happened. The name records the order of discovery while withholding the purpose of the result.
Suppose this fictional value contains normalized email-shaped strings used only in a local test fixture. normalized_addresses describes the transformation. The name does not certify that those strings are deliverable, real or safe to contact. It simply says what this step did.
The distinction between a process diary and a useful label is the point. “Second attempt” can help the person currently experimenting. The next reader needs to know what made that attempt different. A temporary name that survives a refactor should eventually explain its permanent job, even if everyone remains politely surprised that it is still here.
flag: a question without its question
flag announces that a decision exists. It does not identify the decision. When the value is true, should the program send, stop, retry, hide or celebrate?
For an invented display toggle, show_archived_items gives the condition a readable meaning. A true value means the archived items should appear. A reader can evaluate the branch without first interviewing the variable.
Be careful with a name that describes the opposite of its use. A chain of negations can turn a simple condition into a reading exercise. The goal is not to outlaw every negative name. It is to make the ordinary branch easy to say in a sentence and to keep the meaning consistent wherever the value is used.
A boolean is small enough to fit in a very compact representation. The decision it represents can still deserve several words. Saving characters is not useful if the reader has to spend a paragraph reconstructing the question.
result_final: confidence is not a state
result_final sounds reassuring until result_final_v2 arrives. At that point the name has become a prediction about project management, and predictions are a poor substitute for describing a value.
In a fictional report builder, formatted_report tells us the formatting step has happened. If a later step removes empty sections, its output could be report_without_empty_sections. These are not elegant because they are long. They are useful because they distinguish the two objects.
The relevant question is what changes between stages. If the answer is only “this one is newer,” the program may need a clearer structure as well as a better name. A rename cannot supply a distinction that the code itself does not have. It can, however, reveal where the distinction is missing.
x: the traveler far from home
A single-letter name can be perfectly comfortable in a short mathematical expression or a tiny local loop. Move it through several unrelated branches and it starts needing a passport.
The Google TypeScript style guide asks for names that are clear to a new reader while allowing short names in a limited local scope. That is a useful reminder that context matters. The rule is not “longer always wins.”
Our fictional x becomes remaining_attempts when it counts how many tries are left. Now a decrease has an obvious meaning. If it instead represented a horizontal coordinate in a short expression, x could already be doing its job. The field guide should recognize a healthy specimen instead of trying to rename the entire forest.
A name that pays its own rent
PEP 8 emphasizes readability and local consistency, including the importance of a project’s own conventions. It also warns against breaking compatibility merely to satisfy its style guidance. A public identifier can have users outside the file, so changing it is more than a spelling exercise.
For an internal value, ask what the next reader would otherwise need to look up. Its contents, units, state or purpose are good candidates for the name. Include the distinction that matters here. Leave the rest to the surrounding code and documentation.
The language naming committee has similar complaints at a much larger scale. The web development client commandments cover the human version of making assumptions explicit. In either setting, a useful label saves the next person a question. That is a modest ambition, and a surprisingly good reason to retire temp2.