requesting-code-review

Requesting Code Review

Overview

Prepare your code for review before asking others to look at it. A well-prepared review request gets faster, higher-quality feedback and respects the reviewer's time.

Core principle: The author's job is to make the reviewer's job easy. Every minute you spend preparing saves ten minutes of back-and-forth.

Violating the letter of this process is violating the spirit of code review.

When to Use

Always use for:

• New feature PRs
• Bug fix PRs
• Refactoring PRs
• Any PR touching security-sensitive code
• Any PR with breaking changes

Lighter preparation acceptable for:

• Documentation-only changes
• Configuration tweaks
• Single-line fixes with obvious intent

Never skip:

• Pre-Flight Checks (Phase 1) — takes 2 minutes, catches 80% of review round-trips

The Iron Law

NO REVIEW REQUEST WITHOUT PASSING TESTS AND SELF-REVIEW

If tests fail, fix them. If you haven't read your own diff, read it. Requesting review on broken or unreviewed code wastes everyone's time.

Quick Reference

Phase	Purpose	Time
1. Pre-Flight Checks	Validate code is review-ready	~2 min
2. Self-Review	Catch issues before the reviewer does	~5-15 min
3. Change Summary	Explain what, why, and impact	~5 min
4. Test Evidence	Prove it works	~2 min
5. Review Focus Areas	Guide the reviewer's attention	~3 min
6. Review Request Assembly	Format the PR description	~5 min

Phase 1: Pre-Flight Checks

Run before anything else. All must pass.

# Tests passing
npm test
# Expected: all green, zero failures

# TypeScript compilation
npx tsc --noEmit
# Expected: no errors

# Linting
npx eslint .
# Expected: no errors (warnings acceptable)

# Formatting
npx prettier --check .
# Expected: all files formatted

Automated Check

If the project has a validate script, use it:

npm run validate
# Runs all checks in one command

Diff Hygiene