Code review comments can sound harsher than you intend because readers see the words without the voice or facial expression that might soften them in conversation. A bare verdict such as “This is wrong” can also feel abrupt because it identifies a problem without explaining why it matters or what to do next. The fix is to describe the code behavior, explain the concern, make a clear request, and reread the comment from the author’s point of view.
Why written review comments can feel harsher
In a qualitative study of code review engagement, participants said written feedback could come across as harsher than spoken feedback. That reports participants’ perceptions in a research setting; it does not establish that every written comment feels harsher, or that the same effect occurs on every team.
As an Amazon Associate I earn from qualifying purchases.
Writing also strips away cues that help people interpret intent in conversation. If a comment names a flaw but gives no context, the author has to guess whether it is a routine technical correction, a strong objection, or a judgment of their work. Tone and usefulness are related, but not identical: a polite comment can still be unhelpful if it is too vague to act on.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →What makes a comment useful as well as respectful
Describe the code or outcome, not the author
Point to a behavior, result, or requirement rather than making a global judgment. “This is wrong” does not say which case fails. “This branch also runs when the value is empty, so it can return an incomplete result” identifies the issue and its consequence.
#1 Best Overall
- Improve and refine your student's sentence and paragraph skills
- Lessons and activities progress from writing sentences to writing paragraphs
- There are complete teacher instructions and over 70 reproducible models and student writing forms
- Grades 4-6
- 136 pages
Explain why the change matters
A request without a reason can sound arbitrary, even when the concern is valid. A study of 793 Gerrit code review comments found that 42% contained a suggestion without an explanation. That figure applies to the study’s sample, not to code reviews generally. Google’s code review guidance likewise recommends enough explanation for comments to make sense to the author and future readers.
Give a specific next step
Where possible, tell the author what to change. If you do not know the right solution, ask a focused question rather than implying that the author should already know. “Could we add a guard for the empty case?” is more actionable than “Handle this better.”
Rank #2
Make urgency explicit
Authors should not have to infer whether every comment blocks approval. Google recommends labeling severity and distinguishing required changes from guidelines or suggestions. Use your team’s conventions consistently so a request to fix a defect is not confused with an optional style preference.
A four-part structure for a difficult comment
When a point needs more than a quick note, build it from these parts. Not every comment needs all four, but the structure helps make the reasoning and urgency visible.
- Observation: Identify the relevant code behavior or outcome without judging the author.
- Reason: Explain the bug risk, maintenance cost, inconsistency, or requirement behind the concern.
- Request: State a concrete change, or ask a focused question if you are uncertain.
- Severity: Mark the item as required or optional according to your team’s review convention.
For example, “Why did you do this?” can be recast as: “Could you share the constraint behind this choice? I’m concerned it may make retries duplicate the write.” The revised version asks for context and names the technical risk without assigning a motive.
Before-and-after examples
| Less useful wording | More constructive wording | What changes |
|---|---|---|
| “This is wrong.” | “This branch also runs when the value is empty, so it can return an incomplete result. Could we add a guard for the empty case?” | Names the behavior and consequence, then proposes a next step. |
| “Why did you do this?” | “Could you share the constraint behind this choice? I’m concerned it may make retries duplicate the write.” | Requests context and explains the concern without implying bad intent. |
| “Maybe fix this.” | “Suggestion: consider extracting this condition into a helper; it would make the fallback path easier to scan.” | Signals that the change is optional and explains its benefit. |
These are illustrative rewrites, not quotations from a study or from Google’s guidance. The useful distinction is between a vague judgment and a comment that tells the author what you noticed, why it matters, and what kind of response you expect.
How to check the tone before posting
APA reviewer guidance for Qualitative Psychology advises reviewers to reread for tone and asks: “Does your review sound sarcastic, impatient, or harsh?” That guidance is for academic peer review, not a code-review experiment, but the reread is a practical check for any written feedback.
Recommended Free Tools
- Would this sound sarcastic or impatient if the reader could not hear my voice?
- Have I explained why the issue matters?
- Can the author tell what to do next?
- Is it clear whether this is required or only a suggestion?
- Am I describing the code, or making a claim about the author’s competence or motive?
Harshness is not the only problem to watch for
A 2026 paper frames counterproductive code review behavior more broadly than toxicity. Its categories include threats or intimidation, mockery, discouragement without guidance, lack of specification, and combinations of behaviors. This matters because not every negative evaluation or disagreement is an attack, while a comment can be counterproductive without using overtly hostile language.
Best Value
- A Quick Guide for Giving Constructive Feedback on Student Writing
- 8
The paper reports mean recall of 94% ± 13% and average precision of 79% ± 7% for its classifier. Those are the model’s reported performance figures, not estimates of how common harsh or counterproductive comments are. The available sources do not establish a universal formula for tone, a population-wide rate of comments perceived as harsh, or that a particular punctuation mark reliably causes harshness.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
