Phrasing Matters
The same technical observation can land as a helpful suggestion or a personal attack depending entirely on how it is worded. This is not about being soft — it is about being effective. Defensive authors stop listening. Collaborative authors engage and improve.
1. "You" vs. "We" / "The Code"
Avoid directing feedback at the person. Talk about the code itself, or frame it as a shared team concern.
| Toxic | Constructive |
|---|---|
| "You didn't close the file handle here." | "This file handle appears to stay open after the function returns. We should ensure it closes to prevent resource leaks." |
| "You're overcomplicating this." | "This logic is doing a lot at once. Could we simplify it by extracting the validation step into its own function?" |
2. Questions vs. Commands
Commands feel like orders from a superior. Questions invite the author to think, and they leave room for the author to have context you don't. Maybe they tried your suggestion and it didn't work. A question opens a dialogue; a command closes it.
| Toxic | Constructive |
|---|---|
"Rename this variable to user_list." |
"What do you think about naming this user_list? It might be clearer since it holds multiple users." |
| "Use a context manager here." | "Would a context manager (with statement) work here? It would handle the cleanup automatically even if an exception is thrown." |
3. Always Explain the "Why"
A comment without a reason is just noise. The author cannot learn from it, cannot evaluate whether it applies to their specific situation, and cannot push back intelligently if they disagree. The "why" is the most important part of any review comment.
| Toxic | Constructive |
|---|---|
| "Change this loop." | "This loop is O(n²) — for each item, it scans the entire list again. With 10,000 items, that's 100 million operations. A dictionary lookup would bring this to O(n). Want to try that approach?" |
| "Don't do it this way." | "This pattern makes it hard to unit test because the database call is embedded directly in the business logic. If we inject the data access layer as a dependency, we can mock it in tests." |
4. Acknowledge What You Don't Know
Reviewers are not omniscient. Sometimes the author made a deliberate trade-off you are not aware of. Phrasing that acknowledges your own uncertainty ("I might be missing context here, but…") signals intellectual humility and keeps the conversation collaborative.