Code Review

Why We Review Code

Code review isn’t a gate - it’s a collaboration tool. We review code to:

• Catch bugs before they reach production
• Share knowledge across the team so no one is a single point of failure
• Maintain quality and consistency across the codebase
• Learn from each other’s approaches and techniques

What Reviewers Look For

Focus on what matters most:

• Correctness - Does this do what it claims to do? Are edge cases handled?
• Security - Are there injection risks, auth bypasses, or data leaks?
• Readability - Will someone unfamiliar with this code understand it in 6 months?
• Testing - Are the important paths tested? Are tests testing behavior, not implementation?
• Architecture - Does this fit the existing patterns? If it diverges, is there a good reason?

Don’t bikeshed. Naming preferences, formatting opinions, and style nitpicks should be handled by linters and formatters, not humans.

Writing Good PRs

Help your reviewers help you:

• Keep PRs small. Under 400 lines of meaningful change is ideal. Large PRs get slow, shallow reviews.
• Write a clear description. Explain what changed, why, and how to test it.
• Link context. Reference the issue, spec, or RFC that motivated the change.
• Self-review first. Read your own diff before requesting review. You’ll catch the obvious issues.

Turnaround Time

• First review within 24 hours (business hours). If you’re tagged, it’s a priority.
• Don’t let PRs rot. If your PR has been waiting more than a day, ping the reviewer.
• Respond to feedback promptly. The goal is to merge quickly, not to have PRs open for weeks.

Approval and Merge

• One approval required for most changes
• Two approvals for security-sensitive changes, infrastructure, or database migrations
• The author merges after approval - reviewers approve, authors ship