Code Reviews
Code review is the most leveraged activity on a software team. A good review catches defects, spreads knowledge, mentors juniors, and signals what the team values. A bad review feels like a tax. This page covers the mechanics of reviewing PRs on GitHub and the social conventions that make reviews actually work.
Why reviews matter
Quality — a second pair of eyes catches bugs, edge cases, and security issues.
Knowledge sharing — reviewing teaches you the codebase faster than reading it cold.
Mentorship — reviews are where juniors learn the team’s standards.
Documentation — the PR conversation becomes the historical record of why a change happened.
Risk reduction — branch protection requiring approvals keeps half-baked code off main.
The reviewer side
Reading the diff
Open the Files changed tab. GitHub shows a unified or side-by-side diff. Use the file tree on the left to jump between files; tick the checkbox next to a filename to mark it as reviewed (helps you keep track on big PRs).
Leaving inline comments
Hover over a line in the diff and click the blue + icon.
Type your comment in markdown.
Click Start a review (not Add single comment) to batch all your comments.
Drag the + down multiple lines to comment on a range.
Suggestion blocks
Suggestions let you propose an exact edit the author can apply with one click. Use the ± button in the comment toolbar, or write it manually:
In a review comment
This is fine but I think we can simplify: ```suggestion const items = data.filter(Boolean) ```
The three review actions
Action | When to use | Effect |
|---|---|---|
Comment | You have thoughts but no verdict — questions, FYIs | Adds comments, no approval status |
Approve | You’d be happy to ship this as-is | Marks as approved, satisfies branch protection |
Request changes | Something must change before merge | Blocks the merge button until you re-review |
Reviewing a specific commit
From the Files changed tab
Changes from: [ All commits ▼ ] ← drop down lets you pick one commit
├─ a3f2b9c Initial sketch
├─ b71ef02 Address Alice's feedback
└─ c89aabb Fix testsUseful when the author has pushed updates and you only want to re-review what changed since your last pass.
The author side
Responding to comments
Reply in the thread under each comment with your reasoning, a question, or "Done".
Push a follow-up commit with the fix — the new commit appears in the PR automatically.
Click Resolve conversation on threads you’ve addressed; reviewers re-open if you missed something.
For big rework, summarise the changes in a top-level comment so the reviewer knows what to re-look at.
Re-requesting review
After you’ve pushed fixes, click the small circular arrow next to the reviewer’s name in the sidebar to re-request their review. They get a fresh notification and your PR moves back to the top of their queue.
GitHub CLI: gh pr review
Review from the terminal
# Approve with a comment gh pr review 123 --approve --body "LGTM, nice cleanup" # Request changes gh pr review 123 --request-changes --body "See inline comments" # Plain comment gh pr review 123 --comment --body "I’ll defer to @alice on the streaming part" # Open the PR diff locally in your editor gh pr checkout 123
Reviewing locally
Check out the PR branch and poke at it
gh pr checkout 123 npm test npm run dev # Run the change like a user would. The browser is the best reviewer.
Review best practices
Be kind. Critique code, not people. "This function" not "your function". Words matter — they linger in the record.
Be specific. "This is confusing" is useless. "I expected
totalto include tax based on the name — considersubtotalor a comment" is actionable.Ask questions. "Why this approach over X?" invites collaboration. "Do X instead" feels like an order.
Distinguish blockers from nits. Use a label so the author can prioritise.
Approve when ready, even with small nits. Don’t block on style — unblock and let the author choose.
Praise good work. "Nice tests" or "love this rename" costs nothing and changes how reviews feel.
Bound your scope. Don’t demand a rewrite in a 50-line PR.
Conventional comments
A community convention for tagging review comments so the author instantly knows the urgency:
Prefixes that communicate intent
nit: prefer single quotes here suggestion: extract this into a helper, used twice elsewhere question: why guard against null when the API never returns it? issue: this regex will fail on emoji — try the surrogate-pair test praise: lovely use of the new hook API
nit — a small preference, not worth blocking.
suggestion — a concrete change you recommend.
question — you’re unclear, want explanation.
issue — a real bug, must be fixed.
praise — recognising good work.
See conventionalcomments.org for the full taxonomy.
What to look for
Correctness — does the code do what the PR claims?
Tests — are the new code paths exercised? Do tests fail meaningfully when broken?
Error handling — what happens on the unhappy path?
Naming — would a new teammate understand the names six months from now?
Security — any new untrusted input? Authz checks? Secrets?
Performance — N+1 queries? Unbounded loops? Blocking I/O on the request thread?
Backwards compatibility — does this break consumers of the API?
Observability — can you tell when this fails in production?