Code Review — Readable Code That Others Can Maintain

Last verified: June 2026

Why Review

Code is read 10x more than it's written. Every change either reduces or increases the cognitive load for the next person who touches it.

The Checklist

Scan in this order — fastest to slowest:

1. Correctness — Does it do what the PR says?
2. Edge cases — Null, empty, negative, concurrent, retry, timeout?
3. Readability — Would a new dev understand this without asking?
4. Security — Input validation, secrets, injection, auth checks?
5. Performance — N+1 queries, unnecessary loops, missing indexes?

Reducing Cognitive Load

Every variable, condition, and abstraction adds to the reader's working memory. Fewer things to hold = easier to maintain.

Name Things So Code Reads Like English

// Bad — requires reading the method to understand
process(document, true, 3);

// Good — reads itself
validateAndRetry(document, maxAttempts: 3);

Single Responsibility

A function should do ONE thing at ONE level of abstraction. If you can't describe it in one sentence without "and", it's doing too much.

Comments

• Good: Explain WHY (business rule, workaround, gotcha)
• Bad: Restate WHAT the code does
• Worst: Stale comments that contradict the code

Feedback Rules

• Be specific — Point to line numbers, not "somewhere in the file"
• Explain why — "This causes N+1 queries" not just "Change this"
• Suggest alternatives — Give a code snippet showing the fix
• Distinguish must-fix from nit — Use blocking: and nit: prefixes

Red Flags

Stop and look closer when you see:

• // TODO or // FIXME in shipped code
• Commented-out code blocks
• Catch blocks that swallow exceptions silently
• Hardcoded URLs, IPs, credentials, or magic numbers
• Tests that only test the happy path