clean-code-error-handling

name	clean-code-error-handling
description	Use when designing or reviewing exception handling, error boundaries, or error propagation patterns — applies Clean Code error handling principles

Clean Code: Error Handling

Based on Robert C. Martin's Clean Code, Chapter 7: Error Handling.

When to Use This Skill

Trigger on:

• Designing exception handling strategy
• Reviewing try/catch blocks
• Debates about exceptions vs. error codes
• Error propagation across layers/boundaries

Rules

1. Use Exceptions Rather Than Return Codes

Return codes require the caller to check immediately. Exceptions bubble up naturally.

# Bad — caller must check return code
result = transfer(from_acct, to_acct, amount)
if result == ERROR_INSUFFICIENT_FUNDS:
    handle_error()
elif result == ERROR_INVALID_ACCOUNT:
    handle_other_error()

# Good — exception bubbles up naturally
try:
    transfer(from_acct, to_acct, amount)
except InsufficientFundsError:
    handle_error()
except InvalidAccountError:
    handle_other_error()

2. Write Try/Catch First

Structure your error handling before writing the happy path. It forces you to think about what can go wrong.

3. Use Unchecked Exceptions

Checked exceptions break encapsulation. Every callee must know about every exception thrown below it.

4. Provide Context with Exceptions

Always include enough context to determine the source and location of an error.

# Bad
raise ValueError("Invalid")

# Good
raise PaymentProcessingError(
    f"Failed to process payment for order {order_id}: "
    f"insufficient funds (balance={balance}, required={amount})"
)

5. Define Exception Classes in Terms of Caller's Needs

Group by how you want to handle them, not by where they originate.

# Good — grouped by caller's handling needs
class PaymentError(Exception): pass
class InsufficientFunds(PaymentError): pass
class AccountFrozen(PaymentError): pass
class NetworkTimeout(PaymentError): pass

6. Define the Normal Flow

Use the Special Case pattern instead of exception handling for expected conditions.

# Bad — exception for expected case
try:
    total = calculate_total(customer)
except NoActiveSubscription:
    total = 0

# Good — Special Case pattern
class NullCustomer:
    def calculate_total(self):
        return 0

7. Don't Return Null

Returning null forces null checks everywhere. Return a null object or empty collection instead.

8. Don't Pass Null

Passing null into functions is asking for trouble. If a function cannot accept null, assert it early.

Quick Checklist

• Are exceptions used instead of return codes?
• Does each exception include enough context?
• Are exception classes organized by handler needs?
• Is there a Special Case pattern for expected "errors"?
• Are nulls avoided (return empty collections/objects instead)?
• Does every try block have a clear catch?

Source

Distilled from Clean Code by Robert C. Martin, Chapter 7: Error Handling.