A risk-based Python code review method covering correctness, interfaces, failure, data, concurrency, security, observability and delivery evidence.

Production principle

Review the change as a production behaviour: its contracts, state transitions, failure modes, evidence and recovery—not only the diff line by line.

Degraded
async def sync_customer(customer):
    response = requests.post(URL, json=customer.dict())
    db.execute(f"UPDATE customers SET synced=1 WHERE id={customer.id}")
    db.commit()
Repaired
async def request_customer_sync(command: SyncCustomer, uow: UnitOfWork):
    with uow:
        customer = uow.customers.require(command.customer_id)
        customer.request_sync()
        uow.outbox.add(CustomerSyncRequested(customer.id))
        uow.commit()
01

Understand the change surface

Start with the user or operator outcome. Identify which contracts, tables, queues, permissions and deployment assumptions change. A small diff can have a large operational surface when it modifies retry or transaction behaviour.

Ask what must remain true before and after the change. These invariants guide review more reliably than generic style preferences.

02

Trace failure and recovery

Follow the path through validation, durable writes and external effects. Consider timeout, duplicate delivery, concurrent execution and cancellation. Verify that errors leave a state an operator or retry can understand.

Review telemetry alongside behaviour. New failure modes need stable events or metrics, while sensitive values must stay out of logs and traces.

03

Demand proportional evidence

Low-risk refactors may need focused unit tests and static checks. Data migrations, access-control changes and payment or messaging workflows need integration evidence, failure injection and a rollout plan.

A reviewer should be able to state why the evidence is sufficient. Approval is not a guarantee of perfection; it is a documented engineering decision about residual risk.

Review checklist

Evidence to take into review

  • The change has a clear production outcome and bounded scope.
  • Public and internal contracts remain compatible or are versioned.
  • Transactions, retries and concurrency are deliberate.
  • Security and sensitive-data handling are reviewed.
  • Tests and rollout evidence match the consequence of failure.
Continue the inspection

Explore all engineering notes.

Use PRODUCTION-7 to connect this concern with the other dimensions of a trustworthy backend.

View all articles Get the checklist