visual-rhythm

Code Is Prose -- Format It Like Prose

Blank lines are paragraph breaks. They separate ideas. Use them deliberately, not randomly. A function with no blank lines is a wall of text. A function with blank lines after every single statement is a ransom note. The visual structure of your code must match the logical structure. When the eye scans the file, it should immediately see the shape of the logic -- groups, transitions, and boundaries -- without reading a single word.

This is not aesthetic preference. This is readability engineering. Studies on code comprehension consistently show that well-spaced code is understood faster and with fewer errors than dense or randomly spaced code. Whitespace is punctuation. Use it like a writer, not like a toddler with a space bar.

Blank Line Rules

One Blank Line: Between Related Things

One blank line separates related but distinct thoughts. Use it between functions in the same logical group, between logical sections within a function, and between a block of declarations and the first statement that uses them.

# GOOD -- one blank line between logical sections within a function
def process_order(order: Order) -> Receipt:
    # Validate
    validate_order(order)
    validate_inventory(order.items)

    # Calculate
    subtotal = calculate_subtotal(order.items)
    tax = calculate_tax(subtotal, order.shipping_address)
    total = subtotal + tax

    # Persist
    receipt = create_receipt(order, total)
    db.save(receipt)

    return receipt

Two Blank Lines: Between Top-Level Definitions

Two blank lines separate top-level definitions: classes, major function groups, and module-level boundaries. This is Python's PEP 8 standard, but it is good practice in every language. Two blank lines say "this is a new section of the file."

# GOOD -- two blank lines between top-level definitions
class OrderValidator:
    def validate(self, order: Order) -> list[str]:
        errors = []
        errors.extend(self._validate_items(order.items))
        errors.extend(self._validate_address(order.shipping_address))
        return errors

    def _validate_items(self, items: list[Item]) -> list[str]:
        ...

    def _validate_address(self, address: Address) -> list[str]:
        ...


class OrderProcessor:
    def process(self, order: Order) -> Receipt:
        ...