Clean Code & Design Patterns — Judgment, Not Dogma

01First principles: what is "clean" optimizing for?

Code is read 10x more than it's written, and changed by people without the original context. So clean code optimizes for exactly two things:

02Naming — the cheapest documentation

• Name the intent, not the mechanics. days_until_expiry > date_diff2. is_retryable(error) > check(error).
• Precision beats brevity: unverified_webhook_payload tells you something safety-critical that data hides.
• Lie-free names: a function called get_user that also creates one on miss is a landmine — call it get_or_create_user. Misleading names cause more bugs than bad names.
• Booleans read as assertions: is_stale, has_approval, should_retry. Functions are verbs; classes/variables are nouns.
• Scope-proportional length: i is fine in a 3-line loop; module-level names earn full words.
• Encode units and types where ambiguity kills: timeout_seconds, size_bytes, deadline_utc.

03Functions

• One job, one level of abstraction. A function should read like a paragraph at a single altitude — either orchestration (validate(); enrich(); persist(); notify()) or detail, not both interleaved.
• Small-ish, not tiny-for-sport. "Extract until each function is 3 lines" fragments logic into a call-graph scavenger hunt. Extract when a block has a nameable purpose or is reused — not by line count.
• Few parameters; 4+ suggests a missing object (RetryPolicy(max_attempts, base_delay, jitter) instead of three loose args). Keyword-only args (*,) for booleans — send(alert, urgent=True) beats send(alert, True).
• No hidden effects: a function named like a query must not mutate. Command–query separation as a habit, not a law.

Guard clauses over nesting:

def approve(pr, reviewer):
    if pr.state != "open":
        raise InvalidState(pr.state)
    if not reviewer.can_approve:
        raise Forbidden(reviewer.id)
    # happy path proceeds flat, at indent level 1

04SOLID — practical Python, honest caveats

SOLID was coined for 2000s Java; in Python, duck typing and first-class functions satisfy several of these letters almost for free. Present it as coupling management:

HANDLERS: dict[str, Callable[[Event], None]] = {}

def handles(event_type):
    def deco(fn):
        HANDLERS[event_type] = fn
        return fn
    return deco

@handles("issues.opened")
def on_issue_opened(e): ...

@handles("pull_request.closed")
def on_pr_closed(e): ...

def dispatch(e): HANDLERS[e.type](e)
# new events = new functions,
# dispatch never edited

from typing import Protocol

class Notifier(Protocol):
    def notify(self, message: str) -> None: ...

class TelegramNotifier: ...
# no inheritance needed —
# structural typing
class SlackNotifier: ...

# depend on Notifier, not on a
# god-MessagingService with 30 methods

05Composition over inheritance

Inheritance is the tightest coupling in OO: subclasses inherit implementation, so base-class changes ripple invisibly (the fragile-base-class problem), hierarchies are static (one axis of variation, chosen at class-definition time), and deep trees become archaeology.

Composition = build behavior by containing collaborators:

# combinatorial subclassing
class RetryingCachingGitHubClient(
    RetryingClient,
    CachingClient,
    GitHubClient): ...

# n behaviors → 2^n classes,
# MRO puzzles

@dataclass
class ApiClient:
    transport: Transport
    retry: RetryPolicy
    cache: Cache | None = None

client = ApiClient(
    HttpTransport(base_url),
    RetryPolicy(max_attempts=3),
    RedisCache())

Each piece is independently testable and swappable at runtime. Rules of thumb: inheritance is fine for genuine is-a with a stable, shallow contract (framework hooks, exception hierarchies, ABCs defining interfaces); prefer composition whenever you're inheriting to reuse code rather than to be a subtype.

06Dependency injection — the pattern you use daily

DI is just: pass dependencies in; don't construct or import them inside. No framework required in Python.

class IncidentAnalyzer:
    def __init__(self):
        self.llm = OpenAIClient(
            os.environ["KEY"])  # welded in
        self.logs = LokiClient()

class IncidentAnalyzer:
    def __init__(
        self,
        llm: LLMProvider,
        logs: LogSource,
        clock: Callable[[], datetime]
            = datetime.utcnow):
        self.llm, self.logs, self.clock = \
            llm, logs, clock

Now tests pass fakes; prod passes real clients; a provider swap touches one composition point. The composition root idea: wiring happens in one place (your main/app factory), everything below receives its collaborators.

FastAPI makes DI a first-class citizen — this is your daily reality, name it:

def get_llm() -> LLMProvider: return app.state.llm

@router.post("/analyze")
async def analyze(req: AnalyzeRequest, llm: LLMProvider = Depends(get_llm)):
    ...
# tests: app.dependency_overrides[get_llm] = lambda: FakeLLM()

07Patterns actually used in backend work

Frame for interviews: patterns are names for recurring shapes, valuable mostly as vocabulary. These are the ones that genuinely appear in a Python/FastAPI/LLM backend, with when-not-to.

Factory

Centralize "which concrete thing do I build?" — config-driven construction.

def make_provider(cfg: Config) -> LLMProvider:
    match cfg.provider:
        case "anthropic": return AnthropicProvider(cfg.anthropic_key)
        case "openai":    return OpenAIProvider(cfg.openai_key)
        case "local":     return VLLMProvider(cfg.base_url)
    raise ValueError(cfg.provider)

In Python a factory is usually just a function — no AbstractFactoryFactory. Used constantly for provider/gateway selection. skip when there's one implementation and no configurability (YAGNI).

Strategy

Interchangeable algorithms behind one interface — in Python, often literally passing a function.

class ChunkStrategy(Protocol):
    def chunk(self, doc: str) -> list[str]: ...

def ingest(doc: str, strategy: ChunkStrategy): ...
# or simply: def ingest(doc, chunk: Callable[[str], list[str]])

Real uses: retry policies, chunking strategies, routing rules ("cheap model vs frontier model"), scoring functions. Strategy + registry dict = the Open/Closed dispatch shown earlier.

Observer (pub/sub)

Decouple event producers from reactions. In-process: a list of callbacks/signals (Django signals, FastAPI background tasks). At system scale this is Kafka/webhooks — the pattern you live in: GitHub emits, Sentinel subscribes; Sentinel emits to Telegram.

Repository

Put persistence behind a domain-shaped interface:

class IncidentRepo(Protocol):
    async def get(self, id: int) -> Incident | None: ...
    async def add(self, inc: Incident) -> Incident: ...
    async def open_incidents(self) -> list[Incident]: ...

class PgIncidentRepo: ...        # SQLAlchemy inside
class InMemoryIncidentRepo: ...  # tests

Wins: domain logic never imports SQLAlchemy; tests use the in-memory fake; queries have names (open_incidents) instead of scattered filter spaghetti. honest caveat With an ORM already abstracting SQL, a thin repo can be pure ceremony for simple CRUD apps — it earns its keep when domain logic is rich or you genuinely fake persistence in tests.

Adapter

Wrap an external interface so your code sees your interface. This is the pattern of every integration layer — and precisely what an LLM gateway is: Anthropic and OpenAI have different request/response shapes; your adapters normalize both to one internal LLMProvider protocol so the rest of the system is vendor-agnostic. Also: MCP servers are adapters as an architecture — each one adapts a tool/data source to a common protocol. You have unusually good real examples here; use them.

Singleton — the pitfalls section

Intent: one instance, globally reachable. In practice it's global mutable state with a design-pattern alibi:

• Hidden dependency: every user reaches for it invisibly — nothing in signatures reveals the coupling.
• Test poison: state leaks across tests; parallel tests race; you end up monkeypatching module internals.
• Concurrency traps: lazy init needs locking; forked workers (gunicorn!) each get their own copy — "the" singleton isn't single across processes anyway, which also breaks people's caching assumptions.

Patterns to know exist, one line each:

• Decorator — wrap to add behavior: Python's @decorator and every middleware stack.
• Facade — one simple front over a messy subsystem: your gateway again.
• Builder — rare in Python: kwargs + dataclasses cover it.
• Circuit Breaker — distributed-systems pattern: stop calling a failing dependency; relevant to provider fallback.
• Unit of Work — transaction boundary around repos.

08Refactoring smells — recognizing rot early

Smells are symptoms warranting a look, not violations. High-signal ones with their usual fix:

def send_report(report, is_summary):
    if is_summary:
        body = summarize(report)
    else:
        body = render_full(report)
    mail(body)

send_report(r, True)  # True what?

def send_summary(report):
    mail(summarize(report))

def send_full_report(report):
    mail(render_full(report))

# or keyword-only:
def send_report(report, *, summary: bool):
    ...
send_report(r, summary=True)

def approve(pr, reviewer):
    if pr is not None:
        if pr.state == "open":
            if reviewer.can_approve:
                pr.approve(reviewer)
            else:
                raise Forbidden(reviewer.id)
        else:
            raise InvalidState(pr.state)
    else:
        raise ValueError("no PR")

def approve(pr, reviewer):
    if pr is None:
        raise ValueError("no PR")
    if pr.state != "open":
        raise InvalidState(pr.state)
    if not reviewer.can_approve:
        raise Forbidden(reviewer.id)
    pr.approve(reviewer)
# happy path flat, at indent level 1

def handle_signup(req):
    if "@" not in req.email:
        raise BadRequest()
    if len(req.password) < 8:
        raise BadRequest()
    user = User(email=req.email,
                pw=hash_pw(req.password))
    db.add(user); db.commit()
    smtp = smtplib.SMTP("mail:25")
    smtp.send(welcome_email(user))
    track("signup", user.id)
    return user

def handle_signup(req):
    data = validate_signup(req)
    user = create_user(data)
    send_welcome(user)
    track_signup(user)
    return user
# reads like a paragraph at ONE
# altitude: pure orchestration.
# Each step has a nameable purpose —
# that's why it was extracted.

def chunk(doc):
    if isinstance(doc, MarkdownDoc):
        return split_by_headings(doc)
    elif isinstance(doc, PdfDoc):
        return split_by_pages(doc)
    elif isinstance(doc, CodeDoc):
        return split_by_symbols(doc)
    raise TypeError(doc)
# every new doc type edits
# this tested function

CHUNKERS = {
    MarkdownDoc: split_by_headings,
    PdfDoc:      split_by_pages,
    CodeDoc:     split_by_symbols,
}

def chunk(doc):
    return CHUNKERS[type(doc)](doc)
# new doc type = new entry;
# chunk() never edited again

class IncidentAnalyzer:
    def __init__(self):
        self.llm = OpenAIClient(
            os.environ["KEY"])
        self.logs = LokiClient()
# dependencies welded in:
# untestable, unswappable —
# nothing in the signature
# reveals the coupling

class IncidentAnalyzer:
    def __init__(self,
                 llm: LLMProvider,
                 logs: LogSource):
        self.llm, self.logs = llm, logs

# tests pass fakes; prod passes
# real clients; wiring lives at
# the composition root
# (FastAPI: Depends(get_llm))

09Rapid-fire interview Q&A

10Self-test