Code Quality

Code Quality

Structured code review and quality enforcement across common tech stacks. Checklists, linting strategies, and metrics to keep codebases healthy.

Quick Start

Run a Code Quality Check

1. Run static analysis: Linters, type checkers, formatters
2. Review against checklist: Language-specific items below
3. Check complexity metrics: Cyclomatic < 25, data flow < 25
4. Report findings: Structured output with severity and recommendations

Linting Configurations

Rust — Clippy Config

Standard clippy configuration (in Cargo.toml or .clippy.toml):

tomlCopy code
[lints.clippy]
cognitive_complexity = "warn"
pedantic = { level = "deny", priority = -1 }
nursery = { level = "deny", priority = -1 }
unwrap_used = "deny"

Standard commands:

bashCopy code
cargo fmt
cargo clippy --all-targets --all-features -- -D warnings
cargo check
cargo test -- --test-threads=1

Key rules to enforce:

• No .unwrap() in non-test code (use ? or .expect("reason"))
• All public items have rustdoc (#[warn(missing_docs)])
• #[must_use] on functions that return values that should be checked
• When using #[allow(...)], always add a comment explaining why
• If no good explanation exists for #[allow(...)], fix the issue instead

TypeScript — ESLint + Strict Mode

Recommended tsconfig.json strictness:

jsonCopy code
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "exactOptionalPropertyTypes": true
  }
}

Key rules to enforce:

• No any — use unknown and type guards instead
• No // @ts-ignore — fix the type issue or use // @ts-expect-error with explanation
• Prefer const over let, never use var
• Use discriminated unions for state modeling
• Explicit return types on exported functions

Python — Ruff + Mypy

Recommended pyproject.toml:

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

[tool.ruff.lint]
select = ["E", "F", "W", "I", "N", "UP", "ANN", "B", "A", "C4", "DTZ", "ISC", "PIE", "PT", "RET", "SIM", "TCH", "ARG", "PTH", "ERA"]

[tool.mypy]
strict = true
warn_return_any = true
warn_unreachable = true

Key rules to enforce:

• Type hints on all public functions and methods
• Docstrings on all public classes, functions, and methods
• Use pathlib.Path over os.path
• Use uv as package manager
• No bare except: — always catch specific exceptions

Code Review Checklists

Universal Checklist (All Languages)

Correctness:

• Does the code do what it claims to do?
• Are edge cases handled (empty collections, null/None, zero, negative)?
• Are error paths handled gracefully?
• Are there any off-by-one errors?

Clarity:

• Can you understand the code without the PR description?
• Are variable/function names descriptive and consistent?
• Are complex sections commented with "why" (not "what")?
• Is the code self-documenting where possible?

Architecture:

• Does this change respect existing module boundaries?
• Is the change at the right abstraction level?
• Are dependencies reasonable (not pulling in a huge lib for one function)?

Testing:

• Are new functions/methods covered by tests?
• Do tests cover edge cases and error paths?
• Are tests readable and maintainable?

Security (flag for a security follow-up if concerns found):

• No hardcoded secrets or credentials
• User input is validated before use
• No SQL injection, XSS, or path traversal vectors

Rust-Specific Checklist

• cargo fmt applied
• cargo clippy clean (pedantic + nursery)
• No .unwrap() outside tests
• Error handling uses ? with proper error types
• Public items have rustdoc comments
• #[allow(...)] includes explanatory comment
• New functions have unit tests
• Cyclomatic complexity < 25 per function
• Data flow complexity < 25 per function

TypeScript/React-Specific Checklist

• No any types
• Strict mode compliance
• Components have clear prop types
• Hooks follow rules of hooks
• No unnecessary re-renders (check memo/callback usage)
• Bundle impact considered for new dependencies

Django/Python-Specific Checklist

• Type hints present on public interfaces
• Ruff + mypy clean
• No N+1 queries (use select_related/prefetch_related)
• Migrations are reviewed and reversible
• No business logic in views (use service layer)

Complexity Metrics

Cyclomatic Complexity

Measures the number of independent paths through code. Recommended threshold: < 25.

How to reduce:

• Extract helper functions for each branch
• Use early returns / guard clauses
• Replace complex conditionals with lookup tables or pattern matching
• Use strategy pattern for variant-dependent behavior

Data Flow Complexity

Measures how many variables interact within a function. Recommended threshold: < 25.

How to reduce:

• Extract pure functions that take fewer parameters
• Group related parameters into structs/objects
• Split functions that transform data in multiple stages

Measurement Tools

Review Output Format

When delivering a code review:

markdownCopy code
## Code Review: [PR/File/Module]

**Date:** YYYY-MM-DD

### Summary
[1-2 sentences: overall quality assessment]

### Findings

| # | Severity | File | Line(s) | Finding | Suggestion |
|---|---|---|---|---|---|
| 1 | High | src/app.rs | 45-67 | Cyclomatic complexity 28 (limit: 25) | Extract match arms into helper functions |
| 2 | Medium | src/ui.rs | 120 | Unwrap without context | Use `.expect("reason")` or `?` |

### Positive Observations
[What's well-written — acknowledge good code]

### Metrics
- Linter: [clean / N warnings]
- Tests: [pass / fail]
- Complexity: [within limits / violations noted above]

### Security Notes
[Items to flag for follow-up, if any]

Integration

• Can run linters, formatters, and type checkers without asking, per the project's AGENTS.md/CLAUDE.md execution policies.
• Cross-reference: this pack's code-reviewer skill for adversarial review of a focused change set, and design-patterns for fixing complexity violations through better structure.