Module 06: Code Quality and Static Analysis

Why this matters

Tests answer one question: does the code do the right thing at runtime? They say nothing about whether the code is correct in ways that don't show up in a passing test — a function that can hit None on a path your tests didn't exercise, an unused import that hints at dead logic, a parameter you renamed in the signature but not the docstring, a 200-line function nobody can safely change. Static analysis reads your code without running it and catches this entire class of problem: bugs, type mismatches, style drift, and excessive complexity, mechanically, on every file, in seconds. It's the perfect complement to testing — tests explore the runtime behavior you thought to check; static analysis inspects the whole surface of the code for problems you didn't. Together they're your two nets, and they catch different fish.

The higher-leverage reason to care is consistency at scale and speed of feedback. A linter (ruff) enforces one style and flags likely-bug patterns so code review stops wasting human attention on spacing and unused variables. A type checker (mypy) verifies that the types flowing through your program actually line up, turning a class of runtime AttributeError/TypeError into compile-time-style errors you see while writing. Complexity metrics put a number on "this function is too tangled to test or change safely." And pre-commit hooks run all of it automatically before code ever leaves your machine, so the feedback is instant and the mistakes never reach review or CI. This module is about that whole toolchain — and about what "quality" means beyond passing a linter: readability, low complexity, and changeability, which are the properties that actually decide whether a codebase stays healthy.

Concepts

What static analysis is (and how it complements tests)

Static analysis inspects source code without executing it — parsing it into a syntax tree and reasoning about its structure, names, types, and control flow. Because it never runs the code, it needs no test data, no database, no setup; it just reads every line and reports problems. That gives it different strengths from tests:

• Tests verify behavior on the inputs you chose. They can't tell you a variable is unused, a type is wrong on an untested branch, or a function is too complex — those aren't behaviors.
• Static analysis verifies properties of the code itself across all of it at once: syntax/style consistency, likely bugs (unused vars, shadowed names, mutable default args), type soundness, and complexity — but it can't tell you whether your business logic is right, only that it's well-formed.

You need both. A codebase can pass 100% of tests and be riddled with type holes and unmaintainable functions; it can be beautifully typed and linted and compute the wrong total. Static analysis is fast (no runtime), total (every line), and early (as you type) — which is exactly why it belongs in your editor, your pre-commit hook, and your CI, catching the cheap-to-fix problems before a human or a test ever looks.

                       your code
                          |
        +-----------------+------------------+
        |                                    |
     TESTS                            STATIC ANALYSIS
     run the code                     read the code (no run)
     behavior on chosen inputs        every line, all at once
        |                                    |
   "does it do the                   "is it well-formed: typed,
    right thing?"                     lint-clean, simple, consistent?"
        |                                    |
        +----> two nets, different fish <----+

Linting with ruff

A linter flags code that is syntactically valid but stylistically inconsistent or likely buggy. ruff is the modern Python linter and formatter — a single, extremely fast tool (written in Rust) that subsumes what used to be a pile of separate tools (flake8, isort, pyupgrade, and more) and can also format code (a drop-in for black). It does two distinct jobs:

• Formatting (ruff format) — mechanically rewrites code to one canonical layout: line length, quotes, indentation, import ordering. This ends all style debate; there's one format and the tool applies it. No human should ever argue about spacing again.
• Linting (ruff check) — flags rule violations: unused imports/variables, undefined names, mutable default arguments, shadowed builtins, comparisons to None with ==, unreachable code, and hundreds more. Many are auto-fixable (ruff check --fix).

# ruff flags every one of these:
import os                          # F401 unused import
def f(items=[]):                   # B006 mutable default argument (classic bug)
    x = 1                          # F841 local variable assigned but never used
    if status == None:             # E711 comparison to None should be 'is'
        return

The value isn't pedantry — it's that a consistent style makes diffs smaller and review focused on logic, and that a lot of lint rules encode real bug patterns (the mutable default arg above is a genuine, common Python footgun). ruff makes running all of this effectively free.

Type checking with mypy

Python is dynamically typed, but type hints (def total(prices: list[int]) -> int) let a static type checker verify, without running the code, that the types actually line up: that you don't pass a str where an int is expected, don't access an attribute that might be None, don't return the wrong type. mypy is the reference type checker; it reads your annotations and flags mismatches as errors.

def get_user(uid: int) -> User | None:
    return db.get(uid)

def greet(uid: int) -> str:
    user = get_user(uid)
    return f"Hi {user.name}"        # mypy error: user may be None -> no .name

That None bug is exactly the kind of thing that passes every test where the user does exist and blows up in production for the one that doesn't. mypy catches it statically. Key ideas:

• Gradual typing — you can add types incrementally; unannotated code is simply not checked. This lets you adopt mypy on a legacy codebase file by file.
• Strictness is a dial — --strict turns on all checks (no implicit Any, no untyped defs, etc.). Start lenient, ratchet toward strict.
• Types are executable documentation — a signature that says -> User | None tells every caller (and mypy) they must handle absence, enforced mechanically instead of by hope.

Type checking is not a substitute for tests (it doesn't check that your logic is right), but it eliminates a whole category of TypeError/AttributeError/ None-handling bugs that tests often miss.

Complexity metrics: measuring changeability

Beyond correctness and style there's a third axis: how hard is this code to understand and change? Cyclomatic complexity counts the number of independent paths through a function — essentially one plus the number of branches (if, for, and, except, etc.). A function with complexity 3 has three paths and is easy to hold in your head and to test; a function with complexity 25 has twenty-five, is nearly impossible to fully test, and is where bugs breed. Related metrics: cognitive complexity (weights nesting more heavily, closer to human "hard to read"), function length, and parameter count.

These metrics matter because complexity is the leading indicator of maintenance cost: highly complex functions are the ones that get bugs, resist tests (recall module 01 — hard to test usually means badly structured), and scare people away from changing them. Tools like ruff (via its C901 rule) or radon compute complexity and let you set a ceiling, so a function that grows past, say, complexity 10 fails the check and prompts a refactor before it becomes the untouchable monster. The number is a signal, not a law — but a function screaming past the threshold is a reliable prompt to extract, simplify, or split.

Pre-commit hooks: automating the toolchain

Running these tools manually means someone forgets, and inconsistent code reaches the repo. Pre-commit hooks run configured checks automatically at git commit time, on the files you're committing, and block the commit if they fail — so formatting, linting, and type checks happen every time, with no discipline required. The pre-commit framework manages this with a single config file:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.6.0
    hooks:
      - id: ruff          # lint (with --fix)
        args: [--fix]
      - id: ruff-format   # format
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.11.0
    hooks:
      - id: mypy

Now ruff format, ruff check --fix, and mypy run on every commit automatically. The payoff is shifting feedback left: problems are caught on your machine, in the second before they'd have entered history, instead of in CI ten minutes later or in review a day later. The same tools then run again in CI (module 07, track 13) as the enforcement backstop for anyone who bypassed the hook — hooks are the fast local net, CI is the authoritative one.

What "code quality" actually means (beyond style)

It's tempting to equate "quality" with "passes the linter," but that's the smallest part. Quality is fitness for change — how easily and safely the next person (usually future-you) can understand and modify the code. Its real components:

• Readability — names that say what they mean, small functions doing one thing, obvious control flow. A linter enforces style consistency, which aids readability, but can't make a bad name good.
• Low complexity — few paths per unit, shallow nesting, so code fits in your head and is fully testable.
• Correctness of types and contracts — interfaces that say what they take and return, enforced by mypy, so misuse is caught early.
• Testability — which, as module 01 showed, is a proxy for good design: code that's easy to test tends to be well-structured, low-coupling code.
• Consistency — one style, one set of idioms, so the whole codebase reads like it was written by one careful person.

Static analysis measures and enforces the mechanical subset of these (style, types, complexity ceilings) so human review can focus on the parts only humans judge — is this the right abstraction, is the name honest, is the logic sound. Tools don't create quality; they remove the noise so people can attend to the quality that matters. Treat lint/type/complexity as a floor the machine keeps you above, not the ceiling of what good code is.

Command reference

Configuring ruff and mypy in pyproject.toml (one place, versioned with the code):

[tool.ruff]
line-length = 88
target-version = "py312"

[tool.ruff.lint]
select = ["E", "F", "I", "B", "C901", "UP"]   # errors, pyflakes, isort, bugbear, complexity, pyupgrade
# C901 flags overly complex functions; tune the ceiling:
[tool.ruff.lint.mccabe]
max-complexity = 10

[tool.mypy]
python_version = "3.12"
strict = true
warn_return_any = true
warn_unused_ignores = true

A before/after that mypy and ruff would both improve:

# before: untyped, a None hole, a mutable default, an unused import
import json                                   # F401 unused
def load(cfg={}):                             # B006 mutable default
    user = cfg.get("user")                    # user: str | None
    return user.strip().lower()               # AttributeError if user is None

# after: typed, safe, lint-clean
def load(cfg: dict[str, str] | None = None) -> str | None:
    cfg = cfg or {}
    user = cfg.get("user")
    return user.strip().lower() if user is not None else None

Reducing complexity by extraction (what a C901 failure prompts):

# complexity ~12: one function branching on everything (fails max-complexity=10)
def price(order): 
    ...  # nested ifs for discounts, tax, shipping, coupons all inline

# refactored: each concern is a small, testable, low-complexity function
def price(order):
    subtotal = _subtotal(order)
    subtotal = _apply_discounts(subtotal, order)
    return subtotal + _tax(subtotal, order) + _shipping(order)

Hands-on exercises

Work in testing-lab/. Install ruff, mypy, pre-commit, and radon.

1. Format and lint the whole project

Run ruff format . then ruff check .. Read every violation ruff reports. Fix the auto-fixable ones with ruff check --fix . and hand-fix the rest. Commit the now-consistent tree. Note how many were real issues vs. pure style.

2. Catch a real bug with a lint rule

Introduce a function with a mutable default argument (def add(item, bucket=[])) and call it twice, appending each time. Observe the shared-list bug at runtime, then confirm ruff check flags it as B006 statically — before you ever ran it. Fix it (bucket=None + bucket = bucket or []).

3. Add types and let mypy find a None hole

Add type hints to a function that calls something returning X | None and then uses the result without a None check (like the greet/get_user example). Run mypy app/. Confirm it reports the possible-None access. Fix it and re-run to green.

4. Turn strictness up gradually

Run mypy app/ (lenient), note the count, then mypy --strict app/ and note the larger count. Pick one file and get it fully strict-clean (add annotations until zero errors). Reflect: strict mode surfaced how much of your code was implicitly Any.

5. Measure and reduce complexity

Run radon cc app/ -a (or ruff check --select C901 with max-complexity=10). Find your most complex function and refactor it by extracting helpers until it's under the ceiling. Re-measure and confirm the number dropped. Your existing tests (keep them green) prove the refactor preserved behavior.

6. Wire up pre-commit

Add a .pre-commit-config.yaml with ruff (lint+format) and mypy, run pre-commit install, then make a commit that deliberately includes a lint error. Confirm the commit is blocked. Fix and commit successfully. You now have an automatic local net.

7. Distinguish "passes the linter" from "quality"

Take a function that is fully lint- and type-clean but genuinely hard to read (bad names, deep nesting, doing three things). Improve its readability — rename, extract, flatten — without any tool complaining either before or after. Write one sentence on what you improved that no tool measured.

8. Diagnose and fix: green tests, green lint, latent bug

This module passes its tests and ruff check is clean, yet it has a bug mypy would catch and a complexity problem a metric would flag. Find both and fix them.

def classify(score):                       # no type hints
    if score >= 90:
        if score >= 97:
            grade = "A+"
        else:
            grade = "A"
    elif score >= 80:
        grade = "B"
    elif score >= 70:
        grade = "C"
    else:
        grade = None                        # returns None for < 70
    return grade.lower()                    # bug: None.lower() on low scores

def classify(score: int) -> str:
    if score >= 97: return "a+"
    if score >= 90: return "a"
    if score >= 80: return "b"
    if score >= 70: return "c"
    return "f"                              # a real grade, never None

Independent challenge

No code given. Take the layered service from 02-api-layer-and-request-handling (module 06, Handlers, Controllers, and Services) — or any earlier-track project you have — and bring it up to a real static-analysis standard from scratch. Configure ruff (lint + format, with a max-complexity ceiling) and mypy (start lenient, then push one whole module to --strict-clean by adding annotations) in pyproject.toml. Fix every lint and type finding — and treat any possibly-None access mypy reports as a real bug to handle, not to # type: ignore away. Use a complexity metric to find your worst function and refactor it under the ceiling while keeping your existing tests green (proving behavior is unchanged). Finally, wire a .pre-commit-config.yaml running all of it and pre-commit run --all-files to green. The deliverable is a project where ruff check, mypy, and the pre-commit suite all pass, plus one paragraph on a quality improvement you made that no tool measured (a rename, a clearer abstraction).

Common mistakes & troubleshooting

• Treating "passes the linter" as "high quality." Style/type/complexity are the mechanical floor; readability, honest names, and right abstractions are the quality that matters and that tools can't judge.
• Silencing mypy with blanket # type: ignore. Each ignore hides a real question (often a None hole). Fix the underlying issue; if you must ignore, scope it ([error-code]) and comment why.
• Adopting --strict on a whole legacy codebase at once. Overwhelming. Gradual typing: annotate and stricten file by file, ratcheting up.
• Ignoring complexity numbers. A function screaming past the ceiling is where bugs and untestability live. Extract and split before it becomes untouchable.
• Running tools only in CI. Feedback comes ten minutes late. Add pre-commit hooks so problems are caught locally, in the second before commit.
• Formatting debates in review. A total waste of human attention. Adopt ruff format and let the tool decide, once, for everyone.
• Confusing formatting with linting. Formatting rewrites layout; linting/type-checking find bugs and smells. You want all of them, not just the pretty-printer.
• Mutable default arguments and == None. Classic footguns ruff flags for free — don't wave them off as pedantry; they're real bugs waiting for a specific input.

Checkpoint quiz

Write down your answer to each question before expanding it — checking without attempting first is the single easiest way to fool yourself into thinking you've learned this.

1. What does static analysis check that tests structurally cannot, and vice versa? Why do you need both?
2. What are the two distinct jobs ruff does, and why does auto-formatting matter beyond aesthetics?
3. Give a concrete bug class mypy catches that a passing test suite commonly misses, and explain why the tests miss it.
4. What does cyclomatic complexity measure, and why is a high number a reliable signal even though it's not a hard law?
5. What do pre-commit hooks buy you over running the same tools in CI, and why run them in both places?
6. "The code passes ruff and mypy, so it's high quality." What's wrong with that claim, and what components of quality do the tools not capture?
7. mypy reports a possibly-None attribute access. What are your two options, and which is almost always right?

Further reading & sources

• Ruff documentation - Official docs for the fast Python linter and formatter used throughout this module.
• mypy documentation - The reference type checker, including gradual typing and --strict.
• pre-commit.com - The framework for running ruff/mypy automatically at commit time via .pre-commit-config.yaml.
• PEP 484 — Type Hints - The specification that introduced Python's type-hint syntax mypy checks.
• Radon documentation - Tool for computing cyclomatic and cognitive complexity, the changeability metric discussed here.
• Wikipedia — Cyclomatic complexity - Background on McCabe's path-counting metric behind ruff's C901 rule.

Next

07-testing-in-ci-and-test-strategy — you now have tests across every layer and a static-analysis toolchain. Next you'll automate all of it in CI (briefly — track 13 goes deep on CI/CD), learn to triage flaky tests systematically, and design a coherent test strategy that keeps the pyramid balanced as a codebase grows — plus the track's second cumulative review, closed-book over everything from module 00 on.