Code Review
Code review is the practice of having someone else read your changes before they merge — usually via a pull request. It's one of the highest-value habits in software: it catches bugs early, spreads knowledge across the team, keeps the codebase consistent, and quietly raises everyone's standards. Done well, it's a collaborative quality gate; done poorly, it's a bottleneck or a source of friction.
The thing to internalize is that code review is about the code, not the coder. The reviewer and author share a goal — shipping good software — and the best reviews are kind, specific, and focused on helping the change succeed. A healthy review culture makes a team faster and stronger; a hostile or nitpicky one makes people dread shipping.
TL;DR
- Review changes before merge — it catches bugs, spreads knowledge, and keeps code consistent.
- Look for correctness, design, readability, and tests — not just style (automate that).
- Critique the code, not the person; be specific and kind.
- Keep PRs small and reviews timely — both make reviews far better.
Quick Example
A good review comment is specific, kind, and explains the why:
Why It Matters
- Catches bugs before they reach users — cheaper than fixing them in production.
- Shares knowledge — reviewers learn the change; authors learn from feedback. Reduces bus factor.
- Consistency — keeps style, patterns, and architecture coherent across contributors.
- Mentorship — a primary way developers learn and level up.
- Shared ownership — the team, not one person, owns the code.
What to Look For
Automate style and formatting (Code Quality) so humans focus on what matters:
- Correctness — does it do what it claims? Edge cases, error handling, off-by-ones.
- Design — does it fit the architecture? Is there a simpler approach? (See Clean Code.)
- Readability — will someone understand this in six months? Names, structure, clarity.
- Tests — are the changes covered? Do tests actually assert meaningful behavior? (See Test Coverage.)
- Security & performance — obvious risks (injection, secrets, N+1 queries).
💡 Don't bikeshed formatting and naming nits a linter/formatter should own — let tools handle the mechanical rules so review focuses on logic and design.
Giving Good Feedback
- Be kind and specific — explain why, suggest an alternative, point to examples.
- Ask, don't command — "what about handling X?" invites discussion over "do X."
- Distinguish severity — separate blocking issues from optional nits (label nits as such).
- Praise good work — reviews aren't only for problems.
- Critique the code, not the author — "this function" not "you always."
Receiving Feedback Well
- Assume good intent — the reviewer is helping the change, not attacking you.
- Don't take it personally — it's about the code.
- Explain or push back respectfully when you disagree — review is a dialogue.
- Thank reviewers — they spent time helping.
Best Practices
- Keep pull requests small — small PRs get faster, deeper reviews; huge ones get rubber-stamped.
- Review promptly — a blocked teammate is expensive; aim for quick turnaround.
- Automate the mechanical (lint/format/tests) so review focuses on logic and design.
- Be kind and specific, and separate blocking issues from nits.
- Write good PR descriptions — context and why help reviewers enormously.
Common Mistakes
Giant pull requests
Nitpicking style a tool should own
FAQ
What should I actually look for in a code review?
Focus on what tools can't check: correctness (does it work, including edge cases and error handling?), design (does it fit the architecture; is there a simpler approach?), readability (will someone understand it later?), and tests (is the behavior covered meaningfully?). Also flag obvious security and performance risks. Deliberately don't spend your attention on formatting, spacing, or naming conventions a linter/formatter should enforce automatically — that's noise. The reviewer's value is in the judgment calls about logic and design that automation can't make.
How big should a pull request be?
Small — as small as still makes a coherent, reviewable change. Small PRs get reviewed faster and far more thoroughly; reviewers can actually hold the whole change in their head and reason about it. Large PRs (hundreds or thousands of lines) overwhelm reviewers, who then skim and rubber-stamp, defeating the purpose. If a change is inherently big, split it into a series of small, logically-scoped PRs. The discipline of small PRs improves both the review quality and your own thinking about how to break down work.
How do I give feedback without being harsh?
Critique the code, not the person, and make comments specific and constructive: explain why something is a problem, suggest an alternative, and point to examples where helpful. Phrase suggestions as questions ("what about handling the empty case?") rather than commands, distinguish blocking issues from optional nits, and acknowledge good work too. Assume the author wants to ship something good — because they do. The tone that works treats review as two people collaborating toward better code, not one person judging another.
How should I respond to review feedback I disagree with?
Treat it as a dialogue, not a verdict. Assume the reviewer is trying to help and don't take critique personally — it's about the code. If you disagree, explain your reasoning respectfully and discuss it; sometimes you'll surface context the reviewer lacked, sometimes they'll change your mind, and sometimes you'll reasonably agree to differ (or escalate a genuine design disagreement). What matters is engaging in good faith rather than getting defensive or silently complying. And thank reviewers for their time — they're investing in your code's success.
Related Topics
- Clean Code & Best Practices — What good code looks like
- Code Quality Tools — Automating the mechanical checks
- Version Control — Pull requests and branches
- Test Coverage — Reviewing the tests too
- Troubleshooting — Catching issues early