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.
Navigating Nuance: Addressing Specific Concerns with Non-Native Speakers
Understanding the why behind a code review comment is often just as important as understanding the what. For non-native English speakers, this can be particularly challenging. Many phrases that appear straightforward to native speakers carry subtle connotations or grammatical complexities that can lead to misinterpretations and feelings of defensiveness. Let’s focus on how to proactively address concerns raised during a review, especially when you suspect a difference in communication style might be at play.
One common issue is the directness often associated with Western feedback cultures. Phrases like “This doesn’t compile” or “This is inefficient” can feel abrupt and critical, even if intended constructively. A more nuanced approach begins with acknowledging the reviewer’s perspective. Try phrases like: “I appreciate you pointing this out – could you elaborate on what specifically makes it inefficient?” Or, when encountering a compilation error, “Okay, let’s troubleshoot this together. Could you share the exact error message and where in the code it’s happening?” This demonstrates openness to learning and collaboration rather than immediate resistance. Similarly, if someone suggests refactoring, avoid simply saying “No.” Instead, respond with something like: “That’s an interesting suggestion – could we discuss the trade-offs between this approach and the current one? Perhaps there’s a way to achieve the same goal more efficiently.”
Furthermore, it’s crucial to be mindful of idioms and common expressions. Phrases like “clean up the code” can seem vague. Instead, offer concrete suggestions: “Would you mind adding comments explaining the logic behind this section?” or “Could we consider using a different data structure here to improve readability?” Also, don’t hesitate to ask for clarification if something is unclear. A simple question like, “I’m not entirely sure what you mean by ‘maintainability’ in this context – could you give me an example of what you’re looking for?” shows a genuine desire to understand and align with the reviewer’s expectations. Finally, remember that active listening—paraphrasing the reviewer’s comment back to them to ensure understanding—is invaluable. “So, if I understand correctly, you’re concerned about potential scalability issues with this approach?” This simple act can dramatically reduce misunderstandings and foster a more productive dialogue.