Understand the change before commenting
Read the issue, acceptance conditions, and author summary before inspecting individual lines. Identify affected users, interfaces, and stored data. Check whether the diff matches that scope. If the change mixes a feature, migration, and formatting sweep, ask for separation when the combined review becomes difficult to reason about.
Choose reviewers who understand the affected domain and boundaries. A database schema change may need a different reviewer from a visual component. Review ownership should follow knowledge of the risk rather than the number of people available to approve a pull request quickly.
Review behavior and failure paths first
Trace representative inputs through the change and examine what happens when dependencies fail, permissions differ, or values are missing. Compare tests with requirements rather than assuming passing checks settle the review. Look for missing assertions, unrealistic fixtures, and tests that bypass the changed integration boundary.
Illustrative scenario: a bulk update works for an administrator but silently skips permission checks for normal users. Ask for an explicit authorization test and explain the cross-user consequence. This feedback is more actionable than a general request to improve security or add more tests.
Make feedback precise and reviewable
Distinguish blocking correctness issues from optional clarity suggestions. Attach comments to the smallest relevant region and describe the triggering condition. Propose a direction when useful, while leaving room for the author to choose a better implementation that satisfies the same requirement.
After revisions, inspect the updated diff and unresolved threads. Confirm that fixes address the original concern rather than only its wording. Record substantial accepted limitations in the change description so future maintainers can find the decision without reconstructing an extended review conversation.
Working sheet
| Area | Question | Useful follow-up |
|---|---|---|
| Behavior | Which requirement does this implement? | Link acceptance example |
| Failure handling | What happens if the dependency fails? | Add representative failure test |
| Design | Does this responsibility belong here? | Explain boundary or move logic |
| Tests | Can the assertion detect a wrong result? | Demonstrate failure before patch |
Questions about how to conduct a useful code review
Should reviewers block on style preferences?
Use established conventions and automated formatting where possible. Reserve blocking feedback for meaningful quality or correctness concerns.
Can automated checks replace review?
They can enforce known rules and detect patterns, but domain intent and system tradeoffs still need accountable human judgment.
How should I use the working sheet?
Download the CSV and replace the sample rows with evidence from your repository. Record a clear acceptance check and an owner for each item. Keep unresolved assumptions visible rather than treating the example as a completed assessment.
Sources and further reading
Examples are illustrative. They are not customer results, security guarantees, or a substitute for checking the documentation for your installed version.
