I was digging through some old scripts I wrote a few years ago for a client's inventory system, and I found a piece of code that actually made me wince. It works perfectly—it hasn't crashed once—but looking at it now, I realized I have no idea what it's doing without spending five minutes tracing the logic. This is the classic "it works for the computer, but it's garbage for the human" problem.

The "Wait, what does this actually do?" moment

Let's look at this snippet. I'll pretend we're reviewing this together in a PR. This function is supposed to calculate the total value of a warehouse section, but look at the naming:

def calc(l, p):
    t = 0
    for i in l:
        t += i * p
    return t

vals = [10, 20, 5]
prc = 15.5
print(calc(vals, prc))

Technically, this is fine. It runs. But imagine you're coming back to this six months from now. What is l? A list? A length? A location? What is t? Total? Time? Temperature? When you use single-letter variables, you're forcing the next person (which is usually just you in the future) to keep a mental map of every variable's meaning. It's exhausting.

Giving things a proper name

If I rename these to be descriptive, the code starts to document itself. I don't even need a comment to explain what's happening anymore. Let's try this instead:

def calculate_total_inventory_value(item_counts, unit_price):
    total_value = 0
    for count in item_counts:
        total_value += count * unit_price
    return total_value

stock_levels = [10, 20, 5]
price_per_unit = 15.5
print(calculate_total_inventory_value(stock_levels, price_per_unit))

Better, right? Now, notice that I used snake_case for the function and the variables. In Python, that's the standard. If I had used calculateTotalValue (camelCase), it would still work, but any experienced Python dev looking at your code would feel a slight itch in their brain. We follow snake_case for functions and variables because that's what PEP 8—the official style guide—suggests. It makes the ecosystem feel cohesive.

Sorting out the casing chaos

But wait, what if we introduce a class to handle this? This is where the naming rules shift. If I try to name my class inventory_manager, it blends in too much with my functions. I can't tell at a glance if I'm calling a function or instantiating a class.

Watch how this looks when I apply PascalCase to the class name:

class InventoryManager:
    def __init__(self, location):
        self.location = location

    def get_summary(self):
        return f"Inventory for {self.location}"

# Now I can tell immediately that InventoryManager is a class
manager = InventoryManager("North Warehouse")
print(manager.get_summary())

By using InventoryManager (capitalized words, no underscores), it stands out. When you see a word starting with a capital letter in Python, your brain should immediately think: "That's a class."

Making the "magic" numbers obvious

Last thing. I noticed another habit in my old code: "magic numbers." These are random numbers dropped into the middle of logic without explanation. Look at this:

def apply_discount(price):
    return price * 0.85

Where did 0.85 come from? Is it a 15% discount? A tax adjustment? A seasonal sale? If that number changes to 0.82 next month, I have to hunt through the code to find every instance of it. Instead, I'll pull it out into a constant. Constants in Python are written in ALL_CAPS to signal: "Don't touch this value while the program is running."

SEASONAL_DISCOUNT_RATE = 0.85

def apply_discount(price):
    return price * SEASONAL_DISCOUNT_RATE

Now, the code is readable, the intent is clear, and if the discount changes, I only have to change it in one place. It's a small shift in how you write, but it's the difference between a script that "just works" and professional software.

📋 Practical Task

Refactoring the Chaotic Order Processor

Below is a functional but poorly written script for processing customer orders. Your task is to refactor this code to follow Python's naming conventions (PEP 8) and improve its readability.

Requirements:

• Rename the class to use PascalCase.
• Rename functions and variables to use snake_case with descriptive names.
• Identify the "magic number" used for shipping costs and move it into a properly named ALL_CAPS constant.
• Ensure variable names describe what the data is, not just its type (e.g., avoid names like list1).

class order_proc:
    def __init__(self, c_name, items):
        self.cn = c_name
        self.it = items

    def calc_tot(self):
        t = 0
        for i in self.it:
            t += i
        return t + 5.99

c = order_proc("Alice", [10.50, 20.00, 5.25])
print(c.calc_tot())