English for Code Reviews: Phrases That Work
The most effective English phrases for giving, receiving, and responding to code review feedback — categorised by intent and tone.
Effective code review communication is a skill separate from writing good code. The same technical observation can be delivered in a way that motivates the author, or in a way that creates friction and resentment. This guide focuses on the English phrases that produce the best outcomes in real code review workflows.
The Goal: Clarity Without Friction
Before choosing your words, ask: What do I want to happen as a result of this comment? Most review comments aim for one of these outcomes:
- The author fixes a specific thing
- The author considers an alternative approach
- You understand why the author made a choice
- The author feels supported, not attacked
Your language should match the outcome you want.
Opening Comments: Set the Tone
When you start a review, a brief framing comment sets expectations:
“Overall this is a solid PR — I have a few suggestions and one required change before we merge.”
“Good progress here. Most of this looks great. I’ve left some questions where I’d like clarification.”
“This is a big change and I’ve done my best to review it thoroughly. I may have missed things — happy to discuss anything I flagged.”
This kind of opener reduces defensiveness before the author reads any specific comment.
Required Changes: Be Direct, Not Harsh
When something must be fixed, be clear about it — but explain why:
“This needs to be fixed before we merge: the error is swallowed silently here, which means failures will go unnoticed in production.”
“Please update this: the function modifies the input parameter, which will cause unexpected side effects for callers.”
“This is a blocker — the test only passes because the mock is too permissive. Please update the mock to match the actual API contract.”
The pattern: state what needs changing + explain the consequence. This is more persuasive and educational than a bare command.
Suggestions: Signal That They Are Optional
“One thought: you could avoid the nested conditionals here by using early returns. That said, this works fine as-is.”
“Consider pulling this regex into a named constant — it would make the intent clearer. Not blocking.”
“This is just a style preference, feel free to ignore: I’d name this
isLoadingrather thanloadingto match our convention elsewhere.”
Key signals: consider, one thought, feel free to ignore, not blocking, just a preference.
Asking Questions Without Implying Criticism
“I’m not sure I follow the logic here — can you walk me through what happens when
retryCounthits its limit?”
“What was the reason for choosing a
Maphere over a plain object? I’m curious if there’s a performance reason.”
“Can you help me understand this — is the
finallyblock intentional even when there’s nocatch?”
“I might be missing context: is this function called anywhere else, or just from this module?”
The phrase “I might be missing context” is very useful — it signals intellectual humility and invites the author to explain rather than defend.
Responding to Review Comments
Accepting the feedback:
“You’re right — I missed that. I’ve pushed a fix.”
“Good catch. Updated in the latest commit.”
“Fair point. I’ve refactored this and added a test to cover the case.”
Respectfully disagreeing:
“I see where you’re coming from, but I went with this approach because it aligns with how we handle it in the payment module. Happy to change it if you feel strongly.”
“That’s a valid alternative. My concern with it is [reason]. Would you like to discuss this in a quick call?”
Asking for clarification on a comment:
“Could you expand on this comment? I want to make sure I understand what change you’re suggesting.”
“Just to confirm: are you asking me to change the structure, or just the naming?”
Closing a Review Positively
“LGTM — nice clean work here.”
“Approved. The required change looks good after your update.”
“Happy to merge once the test is fixed. Everything else looks solid.”
“Great collaboration on this one. The final implementation is much better than the original design.”
Phrases to Avoid
| Avoid | Why | Better alternative |
|---|---|---|
| ”Why did you do this?” | Sounds accusatory | ”What was the reason for this approach?" |
| "This is wrong.” | Vague and dismissive | ”This will cause X — please fix by doing Y." |
| "Obviously you should…” | Condescending | ”I’d suggest…" |
| "Just…” | Minimises effort | Remove it entirely |
| ”This is terrible.” | Unprofessional | ”This needs significant refactoring before merge.” |
Code review language is a professional craft. Engineers who communicate feedback clearly and kindly get their suggestions acted on more often — and build stronger teams in the process.