Responding to Code Review
Iron Law
EVERY REVIEW COMMENT DESERVES A RESPONSE
Steps
1. Read All Comments First
Before responding to anything, read every comment on the PR.
- Understand the full scope of feedback before reacting
- Look for patterns — multiple reviewers raising the same concern is a strong signal
- Note the severity: is this a blocker, a suggestion, or a style preference?
- Do not start fixing anything until you have read everything
2. Categorize
Sort every comment into one of four categories:
| Category | Description | Action |
|---|---|---|
| Must-fix | Bugs, security issues, correctness problems, failing tests | Fix immediately, no discussion needed |
| Should-fix | Design improvements, better patterns, readability gains | Fix unless you have a strong reason not to, then explain |
| Discussion | Architectural questions, alternative approaches, trade-offs | Respond with your reasoning, be open to changing your mind |
| Nit | Style preferences, minor naming suggestions, formatting | Fix if easy, acknowledge if not, never argue |
3. Address Must-Fix Items
Fix all must-fix items first.
- These are non-negotiable — do not push back on correctness issues
- Commit each fix with a clear message referencing the review comment
- If a must-fix requires a significant change, explain what you changed and why
- Re-run quality checks after fixes
4. Respond to Each Comment
Leave a response on every single comment.
- Must-fix: "Fixed in [commit hash]" or "Fixed — [brief explanation of the change]"
- Should-fix: "Good catch, fixed" or "I considered this but chose X because [reason] — open to changing if you still disagree"
- Discussion: Share your reasoning clearly. Ask clarifying questions if the comment is ambiguous. Be willing to be wrong.
- Nit: "Fixed" or "Acknowledged — keeping as-is because [reason]"
Never leave a comment without a response. Silence reads as dismissal.
5. Re-Request Review
After addressing all comments:
- Push the updated branch
- Leave a summary comment listing what was addressed
- Re-request review from the original reviewers
- If significant changes were made, highlight them explicitly
Red Flags — If You Catch Yourself Thinking:
| Thought | Reality |
|---|---|
| "The reviewer doesn't understand my code" | If the reviewer doesn't understand it, the code isn't clear enough. Improve it. |
| "This nit isn't worth fixing" | Nits take 30 seconds to fix and build goodwill. Just fix it. |
| "I'll address these comments in a follow-up PR" | Address them now. Follow-up PRs for review feedback rarely happen. |
| "The reviewer is wrong about this" | Assume good intent. Explain your reasoning, but be genuinely open to being wrong. |
Rules
- Respond to every comment — no exceptions
- Assume good intent from reviewers
- Fix before defending — if the fix is easy, just do it regardless of whether you agree
- Never dismiss feedback without explanation
- Re-run all quality checks after incorporating changes
- Push fixes as new commits (not amended) so reviewers can see what changed