Thuan: Code reviews are where I get into the most trouble with English. I wrote a PR comment: “This code is wrong. Fix it.” The developer was upset for a week.
Alex: Text has no tone. In person, that might sound like helpful feedback. In a PR comment, it sounds like an attack. Written English requires extra care because there’s no facial expression or voice tone to soften your message.
Thuan: So how do I say “this code needs to change” without making enemies?
Alex: With the same directness — but different framing.
The Code Review Tone Guide
Alex: Every PR comment falls on a spectrum:
| Tone | Example | Impact |
|---|---|---|
| 🔴 Hostile | ”This is wrong.” | Developer feels attacked |
| 🟡 Direct but cold | ”This should use a map instead of a loop.” | Functional but feels rude |
| 🟢 Constructive | ”Consider using a map here — it would simplify the logic and improve readability.” | Developer learns and improves |
| 💡 Teaching | ”Nice approach! One thought: a map might be cleaner here since we’re transforming each item. What do you think?” | Developer feels respected |
Rule of thumb: For junior developers, aim for 💡. For peers, 🟢 works. Never use 🔴.
PR Comment Phrases by Situation
Requesting Changes
| Instead of… | Write… |
|---|---|
| ”This is wrong" | "I think there might be an issue here. [Explanation]" |
| "Fix this" | "Could you take a look at this? I think [suggestion]" |
| "This doesn’t make sense" | "I’m having trouble following the logic here. Could you add a comment or simplify?" |
| "Why did you do it this way?" | "I’m curious about the approach here — what was the reasoning?" |
| "Don’t use this pattern" | "I’d suggest [alternative] instead — it handles [edge case] better” |
Common Comment Prefixes
Use these prefixes to signal intent:
| Prefix | Meaning | Example |
|---|---|---|
| nit: | Nitpick, optional, cosmetic | ”nit: consistent naming — use userId instead of user_id” |
| suggestion: | Non-blocking improvement idea | ”suggestion: extracting this into a helper function might improve readability” |
| question: | Genuinely asking, not criticizing | ”question: will this handle the case where items is null?“ |
| blocking: | Must fix before merge | ”blocking: this SQL query is vulnerable to injection. Let’s use parameterized queries.” |
| praise: | Something good! | “praise: really clean solution. I like how you handled the edge cases.” |
Thuan: Prefixes! That’s so simple and solves so many misunderstandings.
Alex: Exactly. When reviewers use prefixes, the author knows: “Is this a must-fix or just a suggestion?” It removes all ambiguity.
Giving Positive Feedback
Many reviewers only comment on problems. That makes code review feel like punishment. Balance it:
| Situation | Comment |
|---|---|
| Clean code | ”This is really well-structured. Nice job.” |
| Good pattern | ”Great use of the strategy pattern here.” |
| Thorough tests | ”Love the test coverage, especially the edge cases.” |
| Improvement | ”This is much better than the previous approach. 👍“ |
| Learning | ”TIL! I didn’t know about this API. Thanks for using it.” |
Thuan: I never leave positive comments. I only comment when something’s wrong.
Alex: That means your team associates your name on a PR with “problems.” Start leaving one positive comment per review. It changes the entire dynamic.
Receiving Code Review Feedback
Thuan: What about when someone reviews my code and leaves harsh comments?
Alex: Here’s how to respond professionally:
When the Feedback Is Valid
| Situation | Response |
|---|---|
| Agree with the change | ”Good point. Updated.” |
| Need to think about it | ”Let me think about this — I’ll update before EOD.” |
| Agree but want context | ”You’re right. I initially did it this way because [reason], but your approach is better.” |
When You Disagree
| Situation | Response |
|---|---|
| Different trade-off | ”I see your point. I went with this because [reason]. But I’m open to changing it — what do you think about [compromise]?” |
| Performance vs readability | ”I optimized for performance here because this runs 10K times per request. Would a comment explaining the approach be enough?” |
| Not worth changing | ”I hear you. My concern is that refactoring this now would touch [X files]. Could we add a follow-up ticket instead?” |
When Comments Are Rude
| Rude Comment | Professional Response |
|---|---|
| ”This is bad code" | "Could you be more specific about what you’d change? I’d like to understand your concern." |
| "Why would you do this?" | "There were a few factors: [reason]. Would you suggest a different approach?" |
| "I would never do it this way" | "I’m open to alternatives. What approach would you recommend?” |
Golden Rule: Never respond to heat with heat. In async text, tone escalates fast.
Writing PR Descriptions That Save Time
Thuan: My PR descriptions are usually one line: “Fix search bug.”
Alex: That forces every reviewer to read all the code to understand what’s happening. A good PR description saves everyone time:
PR Description Template
## What
Brief description of the change.
## Why
The problem or requirement this solves.
## How
Technical approach — key decisions and trade-offs.
## Testing
How you tested this. What to verify during review.
## Screenshots (if UI change)
Before / After screenshots.Example
## What
Fix checkout failing for carts with 50+ items.
## Why
Bug #1234: Large carts caused an unbounded DB query
that timed out after 30 seconds.
## How
- Added pagination to the cart query (20 items per batch)
- Added index on `cart_id` column
- Added test for carts with 100+ items
## Testing
- Unit test: `test_large_cart_checkout` (added)
- Manual test: tested with 200 items on staging
- Performance: query time dropped from 30s to 200ms
## Notes
- No migration needed, index is added automatically
- This changes the API response shape for `/cart`
(now paginated). Updated API docs.Thuan: That PR description answers every question before anyone asks.
Alex: And it makes reviewing faster. Reviewers know what to focus on: “Check the pagination logic and the new index.”
Team-Level Code Review Culture
Thuan: As a tech lead, how do I set the code review culture?
Alex: Establish team norms:
Suggested Team Agreements
| Agreement | Why |
|---|---|
| ”PR reviews within 24 hours” | Unreviewed PRs slow the whole team |
| ”Use comment prefixes: nit/suggestion/blocking” | Removes tone ambiguity |
| ”One positive comment per review” | Makes reviews less punishing |
| ”Author resolves comments” | Clear ownership of follow-up |
| ”Disagreements → 5-min call” | Text arguments are a waste of time |
Setting Expectations (Email/Slack Message)
“Hey team, I’d like to propose some code review norms:
- Please review PRs within 24 hours
- Use prefixes:
nit:,suggestion:,blocking:- Leave at least one positive comment per review
- If a discussion has more than 3 back-and-forth comments, jump on a quick call
These are suggestions — let’s discuss in our next retro and decide together.”
10-Minute Self-Practice
The Comment Rewrite (5 min)
- Open a recent code review you gave
- Find your most “direct” comment
- Rewrite it using: prefix + suggestion + reason
- Example: “This is wrong” → “suggestion: consider using a Map here — it handles duplicates automatically and simplifies the lookup logic”
The PR Description Practice (5 min)
- Open your latest merged PR
- Rewrite the description using the template (What/Why/How/Testing)
- Use it as a template for your next PR
What’s Next
Your code reviews are now constructive and clear. Next post: Talking to Non-Technical Stakeholders — translating tech to business language for people who don’t know (or care) what an API is.
This is Part 10 of the English Upgrade series. Related: English Upgrade #5: Technical Writing — extend your PR writing skills to docs and ADRs.
Also see: Tech Coffee Break #8: CI/CD — because good PRs are part of good pipelines.