Code Readability

Code is read ten times more often than it is written.

The idea

Readability isn't just about aesthetics; it's a core engineering metric that dictates how fast a team can move safely. When code is highly readable, onboarding is faster, bugs are easier to spot, and refactoring is less risky.

Good readability is achieved through clear naming, consistent formatting, early returns (guard clauses) to reduce nesting, and separating distinct concepts into their own functions.

How it works (Early Returns)

Instead of wrapping the entire "happy path" inside a massive `if` statement, handle edge cases at the top of the function and return immediately. This keeps the core logic at the root indentation level.

# VULNERABLE TO UNREADABILITY: The Arrow Anti-Pattern
def process_order(order):
    if order is not None:
        if order.is_paid:
            if not order.is_shipped:
                # Do 50 lines of complex shipping logic
                return True
    return False

# SECURE (READABLE): Guard Clauses
def process_order(order):
    if order is None or not order.is_paid or order.is_shipped:
        return False
        
    # Do 50 lines of complex shipping logic cleanly
    return True

Watch out for

• Magic Numbers: Using `if status == 4:` instead of `if status == Status.SHIPPED:`. Always use constants or Enums.
• Clever One-Liners: Compressing 5 lines of logic into a massive nested list comprehension just to save vertical space. "Clever" code is the enemy of readable code.
• Boolean Blindness: Calling a function like `update_user(user, True, False)`. The reader has no idea what True and False mean. Use named arguments: `update_user(user, is_admin=True, send_email=False)`.

Worked example

You review a PR where a developer named a variable `d` and another `data`. Ten lines down, they call `process(d)`. It takes you three minutes of scrolling up and down to realize `d` is a `Date` object and `data` is a `Dictionary`. If they had simply used `current_date` and `user_payload`, the review would have taken seconds.

Check yourself

Which variable name is objectively the most readable in the context of an e-commerce cart?