Code Review Communication: How to Give Clear, Constructive Feedback
Code review is a communication exercise disguised as a technical one. The diff is the easy part. The hard part is writing feedback that is clear enough to be understood on the first read, direct enough to be actionable, and kind enough that the author does not feel attacked. This balance is difficult in any language. It is exponentially harder when the reviewer and the author speak different native languages.
In a 2023 survey of over 4,000 developers, "unclear or ambiguous feedback" was cited as the number one frustration with code reviews, ahead of slow turnaround time and nitpicking. The problem is not that reviewers have bad intentions. The problem is that written text lacks tone of voice, facial expressions, and the real-time feedback loop of a conversation. A comment that sounds helpful in the reviewer's head can read as dismissive or hostile to the author.
The Communication Challenge
Consider this review comment: "Why did you do it this way?" Depending on who reads it, this is either:
- A genuine question from someone who wants to understand the reasoning
- A passive-aggressive suggestion that the approach is wrong
- A rhetorical question implying the author should have known better
All three interpretations are valid. The reviewer intended the first one. The author, already anxious about their code being scrutinized, read the third one. This happens constantly, and it is the root cause of most code review friction.
The problem compounds in cross-cultural teams. Communication norms vary dramatically across cultures. In some cultures (Dutch, Israeli, German), direct criticism is expected and appreciated. In others (Japanese, Korean, Thai), direct criticism of someone's work is deeply uncomfortable and should be softened with context. Neither approach is wrong, but when they collide in a PR comment thread, misunderstanding is almost guaranteed.
Tone and Language Patterns That Work
1. Lead with the "What" Before the "Why Not"
Instead of pointing out what is wrong, suggest what would be better. This reframes the comment from criticism to collaboration.
data to userProfiles to make the contents clearer at the call site."
2. Use "We" Language for Shared Standards
When the feedback is about a team convention rather than a personal preference, frame it as a shared standard. This removes the reviewer-vs-author dynamic.
const by default and let only when reassignment is needed (per our style guide)."
3. Prefix Comments with Intent
A simple label at the start of a comment eliminates ambiguity about how seriously the author should take it. Many teams adopt conventions like:
- nit: Minor style issue. Not a blocker. Fix if you agree, ignore if you do not.
- suggestion: An alternative approach to consider. Not mandatory.
- question: Genuinely asking. Not implying the code is wrong.
- blocking: This must be addressed before the PR can be merged.
- praise: Something done well that is worth calling out.
nit: Trailing whitespace on line 42.
question: Is there a reason we are using setTimeout instead of requestAnimationFrame here? I am not sure about the trade-offs.
blocking: This query is vulnerable to SQL injection. We need to use parameterized statements.
4. Ask Questions That Are Clearly Questions
If you are genuinely asking a question, make it impossible to misread as a rhetorical jab. Add context about why you are asking.
5. Provide Code Suggestions, Not Just Descriptions
Whenever possible, show the code you are suggesting, not just describe it. GitHub's "Suggest changes" feature is perfect for this. A concrete diff is unambiguous in a way that prose cannot be.
// Before
const name = user && user.profile && user.profile.name;
// After
const name = user?.profile?.name;How to Be Direct Without Being Rude
There is a persistent myth in software culture that being direct and being kind are opposites. They are not. Directness saves the author time. Kindness preserves the relationship. You can do both.
The formula is: observation + impact + suggestion.
- Observation: What you noticed in the code (factual, not judgmental)
- Impact: Why it matters (performance, readability, maintainability, correctness)
- Suggestion: What to do about it (specific, actionable)
response.data is null (observation). If the API returns a 204, this will throw a TypeError at runtime (impact). Adding a null check before accessing .items would prevent the crash (suggestion)."
L1-Specific Communication Patterns
Being aware of how different native languages influence English writing style helps both reviewers and authors communicate more effectively.
- East Asian L1 speakers (Chinese, Japanese, Korean): Tend to soften feedback extensively ("Maybe it would be slightly better if..."). This indirectness can cause native English speakers to miss that a serious concern is being raised. If you are an East Asian L1 speaker writing reviews in English, consider using the prefix labels (nit/suggestion/blocking) to make the severity clear without feeling overly direct.
- German and Dutch L1 speakers: Tend to be very direct, which can feel harsh to English readers who expect more hedging. Phrases like "This is wrong" or "You need to change this" are normal in German workplace communication but read as aggressive in English. Adding a brief "why" softens the directness without losing clarity: "This needs to change because the current approach has O(n^2) complexity on every keystroke."
- Romance language L1 speakers (French, Spanish, Italian): Sometimes write longer, more elaborate sentences that can be hard to parse quickly in a code review context. English code review comments work best when they are short. One point per comment. If you have three things to say, write three separate comments.
- South Asian L1 speakers (Hindi, Telugu, Tamil): May use honorific patterns that create unnecessary formality in code reviews. "Sir, I kindly request you to consider..." is polite but slows down the communication. In code review context, casual directness is the norm: "Consider using X instead of Y because..."
Giving Positive Feedback
Code reviews are not only for catching problems. Calling out well-written code reinforces good patterns and builds trust. A review that only contains criticism, even if every comment is polite, creates a negative association with the review process.
Good positive feedback is specific, not generic. "LGTM" and "Nice!" do not teach anything. "This error handling is excellent -- catching the specific exception type and including the request ID in the error message will make debugging much easier in production" tells the author exactly what they did well and why it matters.
Automating Writing Quality in Reviews
The BeLikeNative Chrome Extension runs in the background while you write PR comments in GitHub, GitLab, and Bitbucket. It catches ambiguous phrasing, suggests clearer alternatives, and flags tone issues before you post. Think of it as a linter for your review comments.
For non-native English speakers, it is particularly useful because it catches the L1 transfer patterns described above: missing articles, wrong prepositions, overly indirect phrasing, and sentences that are too long for quick scanning. You write your review naturally, and the extension suggests improvements in real time.
Write Clearer Code Reviews
Get real-time suggestions on tone, clarity, and grammar while writing PR comments.
Chrome Extension Try BeLikeNative Free