The Code You Can't Read Is the Code You Can't Fix
Open a program you wrote three weeks ago. If the variables are called x, data, tmp, and stuff, you are not reading code — you are decoding it. You wrote it, and you still have to work out what t holds before you can change anything. Now imagine your teacher, your teammate, or a recruiter opening the same file. They have no memory of what you meant. If the names do not explain the code, nothing does.
This is why naming is the first readability skill worth learning, before design patterns and before clever shortcuts. You will read far more code than you write — your own old code, your classmates' code, library code, and the code an AI assistant just generated for you. A clear name is the cheapest documentation you will ever write: a few extra characters that pay off every time someone reads the line. And names do more than explain. A well-named program makes its bugs visible, because a wrong step reads wrong.
What a Good Name Actually Does
A name answers one question: what is this, exactly? total_price_in_cents answers it. total does not — total of what, in what units, before or after tax? The reader has to go and find out, and every trip away from the line they are reading is a chance to lose the thread.
Test every name out loud. Say "the variable t holds the running total in cents" — if you have to add words the name does not contain, the name is lying by omission. Now say "the variable total_price_in_cents holds the running total in cents." Nothing to add. That is the test: a good name says in code what you would say in a sentence. Apply it to functions too. A function called calculate_average promises one thing and does it. A function called do_stuff promises nothing, so nobody can tell when it is broken — including you, three weeks from now.
Four Rules for Names That Tell the Truth
Four rules cover almost every name you will write as a student.
Be specific, not clever. Call it what it is: student_scores, not s. A list of prices is prices, not items, when the next function also has a list of items that means something else. Specific beats short every time — your editor completes names for you, so the extra typing is imaginary.
Say the units. A number without units is a guess. total_cents and total_dollars are different values with the same digits. price_in_euros, delay_in_seconds, weight_in_kg — put the unit in the name and the off-by-a-hundred bug has nowhere to hide.
Verbs for functions, nouns for values. Functions do things, so name them with a verb: calculate_average, save_version, find_top_scorer. Values hold things, so name them with a noun: average_score, top_scorer. When a function name is a noun — average(scores) — the reader cannot tell whether it computes the average or returns one that is already stored.
One word, one meaning. If scores means a list of exam marks in one function, do not let scores mean a list of game points in the next. Pick one word per idea and use it everywhere. Consistency is what lets a reader trust a name the second time they see it — and it is what makes searching your code work, because one word finds every use.
Try It: Rename the Mystery
Here is the same checkout code twice: once with mystery names, once with honest ones. Paste it into the browser editor and run it.
# checkout.py — the same code, once with mystery names, once with honest ones
def calc(items, member): t = 0 for p in items: t += p if member: t -= 10 return t def checkout_total(prices, is_member): total = 0 for price in prices: total += price if is_member: total = max(0, total - 10) # $10 off once, never below $0 return total prices = [20, 15, 10]
print("Mystery names, member:", calc(prices, True))
print("Honest names, member:", checkout_total(prices, True))
print("Honest names, not a member:", checkout_total(prices, False))
print("Honest names, empty cart:", checkout_total([], True))The mystery version prints Mystery names, member: 15 for a member — a $10 discount taken three times, once per item, because the subtraction sits inside the loop. Nothing in the names objects: t, p, and 10 could be anything. The honest version prints Honest names, member: 35: the same $10, taken once, after the loop, and clamped so an empty cart prints Honest names, empty cart: 0 instead of going below zero. The bug did not change. The names changed — and the bug became obvious. You do not find bugs like this by staring harder. You find them by making the code say what it means.
Try it yourself: take a program of yours with single-letter names and rename one variable at a time, running the code after each rename. If a rename feels hard — if you cannot decide what to call something — that is information: you do not yet know what the value is for. Sort that out first, and the name usually writes itself.
Renaming Is Safe When You Do It in Small Steps
Students avoid renaming because it feels risky: change a name in one place, miss it in another, and the program breaks. The fix is small steps. Rename one thing, run the code, and only then rename the next. Python will not catch a missed rename for you — there is no compiler checking names — so running the code after every rename is the check. Save a version before you start, so a bad rename costs you one restore instead of one evening. CoderFile saves versions automatically as you edit a snippet, and Version History lets you diff and restore in one click — the save-a-version habit covers exactly this job.
Ask for help when you are stuck on a name. Paste the function into CoderFile's AI assistant and ask it to suggest clearer names — that is one of the best uses of your 10 free AI requests a day, because a suggested name teaches you how an experienced reader would describe your code. Then save the renamed version as a snippet, with a note saying what you renamed and why — a future employer reading your snippets sees code that explains itself.
When Good Names Fill Your Free Plan
Stay on Free ($0: 20 executions a day, 10 AI requests a day, 10 saved snippets, 3 private snippets, 3 collaborators per snippet) while it fits — it is enough to rename real coursework and run it after every rename. But readable code is code you keep, and ten saved snippets fill up fast once you save every working version. That is the upgrade moment, not a sales pitch: when you have to delete a good version to save a new one, Pro earns its $9/month or $69/year — unlimited saved snippets and executions, 100 AI requests a day, 10 collaborators per snippet, unlimited private snippets, and GitHub integration, which Free does not include. Team ($19/user/month, or $15/user/month billed annually) covers a class renaming together — see the full comparison on the pricing page.
Your next step is a ten-minute rename: open the messiest program you wrote this term and rename five variables until each one passes the say-it-out-loud test, running the code after every rename. Save the result as a snippet called "renamed for readability" and compare it with the original — the difference is the skill. Then read the debugging routine next: once your code says what it means, the bugs have nowhere to hide.