The Art of Naming Variables

Naming your variables is one of the hardest things to get right in programming. A lot of the time, you will be reading code rather than writing it — and the difference between a good variable name and a bad one is more than just aesthetics. It directly impacts the readability and long-term maintainability of a codebase.

Single-character names

Single characters are the worst offenders. Take the function below — can you tell what it does? What are p, d, and a? What does x return?

def c(p, d, a):
    x = 0
    for i in p:
        if a:
            x += i - (i * d)
        else:
            x += i
    return x

You might work it out eventually, but it takes effort. Now look at the same logic with meaningful names:

def calculate_total_price(prices, discount_rate, apply_discount):
    total = 0

    for price in prices:
        if apply_discount:
            discounted_price = price * (1 - discount_rate)
            total += discounted_price
        else:
            total += price

    return total

Immediately clear. The function calculates a total price, optionally applying a discount to each item. Time spent on naming variables is time saved the next time anyone — including future you — touches that code.

Abbreviations

Abbreviations can be useful, but they are often a silent source of confusion. Take this:

new_res = "some value"

What does new_res mean? A new result? A new resource? A new response? If names like this are scattered throughout a codebase, you will constantly find yourself clicking into variables to understand their purpose — unnecessary overhead that kills flow.

new_result = "some value"

Three extra characters. Completely unambiguous.

Misleading names

A misleading variable name is one that implies something that isn't true. This is arguably the most dangerous category because the code looks correct at a glance.

is_admin = get_user_role(user)  # returns "admin", "user", or "guest"

if is_admin:
    # This runs for ANY non-empty string, not just admins
    do_admin_stuff()

The name is_admin implies a boolean, but get_user_role returns a string like "admin", "user", or "guest". The if is_admin check will pass for any non-empty string — meaning every logged-in user effectively gets admin-level access. A ticking time bomb.

user_role = get_user_role(user)

if user_role == "admin":
    do_admin_stuff()

# or, wrap it in a proper boolean function

def is_user_admin(user):
    return get_user_role(user) == "admin"

if is_user_admin(user):
    do_admin_stuff()

Either rename the variable to reflect what it actually holds, or encapsulate the boolean logic in a dedicated function that makes the intent impossible to misread.

So what actually matters?

A variable name should answer the question: "what does this thing represent?" — without requiring any surrounding context. If you have to look at where a variable is defined or how it is used to understand its purpose, the name is doing its job poorly.

Honestly, I'm guilty of all of this. There are functions I wrote when I started programming that I can barely read today — and the only person I have to blame is past me who couldn't be bothered to type three extra characters. It's one of those things that feels fine in the moment but compounds fast the bigger a codebase gets. The next developer to read your code might be a friend, a future employer, or just you at 11pm trying to fix a bug. Your future self will thank you :)