python-clean-code

Clean Code Python

Apply these principles whenever writing or refactoring Python code. Don't narrate the framework to the user — just produce code that embodies these values. Use the self-review checklist before presenting any non-trivial code.

Before writing code

Think through: what is the single responsibility of this component? What are its dependencies? What will callers need from it? Design the interface and type signatures before the body. Only implement what the current requirement demands.

---

Principles

SRP — Single Responsibility Principle

One class, one reason to change. If a class touches persistence AND domain logic AND notifications, split it.

# Bad: three responsibilities in one class
class User:
    def save(self) -> None: ...          # persistence
    def send_welcome_email(self) -> None: ...  # notifications
    def validate_email(self) -> bool: ...  # domain rule

# Good: one class per responsibility
class User: ...              # domain model only
class UserRepository: ...    # persistence
class UserMailer: ...        # notifications

SoC — Separation of Concerns

Cross-cutting concerns (logging, caching, auth, retries) belong in decorators or middleware, not scattered inline inside business methods.

# Bad: logging woven into business logic
def get_user(user_id: int) -> User:
    log.info("Fetching user %d", user_id)
    user = db.query(User).get(user_id)
    log.info("Fetched %s", user.name)
    return user

# Good: concern at the boundary, not the body
@log_call
def get_user(user_id: int) -> User:
    return repo.get(user_id)

SLA — Single Level of Abstraction

Every line in a function should live at the same conceptual level. Don't mix raw SQL with domain calls or HTTP requests with UI logic.

# Bad: two levels in one function
def process_order(order_id: int) -> None:
    row = db.execute("SELECT * FROM orders WHERE id=?", [order_id]).fetchone()
    order = Order(id=row[0], total=Decimal(row[1]))
    send_confirmation_email(order.customer_email)

# Good: uniform level of abstraction
def process_order(order_id: int) -> None:
    order = order_repo.get(order_id)
    notifier.send_confirmation(order)