A good code review comment identifies the behavior or decision at issue, explains why it matters, and makes the next step clear. It also signals whether the change is required or merely suggested. That keeps feedback focused on the code, rather than the author, and helps the author judge the concern and respond.
What makes a code review comment useful?
Google’s Engineering Practices guidance puts the balance plainly: “In general, it is important to be courteous and respectful while also being very clear and helpful to the developer whose code you are reviewing.” (How to write code review comments.) In practice, a strong comment gives the author enough context to understand and act on the feedback without turning a review note into a personal judgment or an attempt to dictate every detail of the fix.
As an Amazon Associate I earn from qualifying purchases.
- Point to something observable: a line, branch, behavior, missing case, or design choice.
- Explain the reason: state the consequence, risk, or relevant team standard, and avoid claiming an impact you have not established.
- Make the next step understandable: ask for a change, a test, or clarification; offer a concrete approach when it would help.
- Label the intent: make clear whether the request blocks approval or is optional feedback.
- Keep the tone professional: address the code and its effects, not the developer’s ability or motives.
How do you turn criticism into actionable feedback?
A rhetorical question can sound like an accusation and leaves the author to infer what change you want. Replace it with an observation, a reason, and a recommendation. Google gives this example:
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →“The concurrency model here is adding complexity to the system without any actual performance benefit that I can see. Because there’s no performance benefit, it’s best for this code to be single-threaded instead of using multiple threads.”
The point is not that concurrency is inherently bad. The comment works because it names the tradeoff the reviewer sees and connects that concern to a recommendation. If you do not know whether the code has a performance benefit, state what you observed and invite the author to share relevant context rather than presenting an unverified conclusion as fact.
Use a behavior–impact–request pattern
For a correctness concern, a useful adaptable structure is: “This branch also runs when [specific condition]. That means [specific user or system consequence]. Could we handle [condition] here, or add a test that captures the intended behavior?” Replace the bracketed parts with details from the code and tests. The request should match the problem: sometimes a targeted test or clarification is enough; sometimes the code needs to change.
Rank #2
Give a concrete suggestion when it helps
Offer a direct alternative if it makes the desired outcome easier to see or avoids unnecessary back-and-forth. But you do not need to design the whole fix in every comment. If the author has better local context, describe the problem and leave room for a sound alternative.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
How should you mark required and optional comments?
Authors need to know which comments must be addressed before approval and which are suggestions. Reserve blocking language for issues that affect correctness, security, maintainability, or an agreed team standard. Label minor preferences and educational notes so they do not look like requirements. Google’s guidance gives labels such as “Nit,” “Optional (or Consider),” and “FYI.”
Rank #3
| Intent | Example | When it fits |
|---|---|---|
| Required change | “This input can be empty, so the current indexing operation can fail. Could we handle the empty case before merging?” | A concrete failure or other issue needs to be fixed before approval. |
| Optional suggestion | “Nit: would retryDelay make this name easier to understand at the call site? No need to change it if the team convention favors the current name.” |
A possible improvement is useful, but the current approach is acceptable. |
| Informational note | “FYI: this helper also handles the empty input case, so the caller does not need a separate check.” | The author may benefit from context, but no change is being requested. |
Do not make an optional preference sound mandatory just because you would have chosen a different style. Google’s Standard of Code Review says: “If the author can demonstrate (either through data or based on solid engineering principles) that several approaches are equally valid, then the reviewer should accept the preference of the author.”
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.How can you make review feedback more constructive?
Comment on the code, not the person
Describe what the code does and why that matters. Avoid attributing carelessness, inexperience, or intent to the author. A comment about an extra branch, unclear name, or unhandled case gives the author something concrete to evaluate; a comment about what the author supposedly understands does not.
Recognize effective work specifically
Positive feedback is most useful when it names the choice and its benefit. For example: “Keeping the parsing change separate from the formatting cleanup makes the behavior easier to review. Thanks for splitting them.” This tells the author which practice helped, rather than offering praise with no actionable meaning.
Free tools Windows power users keep installed
One-click scans. No signup required.
Match the channel to the disagreement
A focused question about a specific line usually belongs in the review thread. If a disagreement becomes repeated or needs nuanced discussion, Google’s reviewer guidance recommends a respectful private conversation and, when necessary, escalation through appropriate management channels. Keep the exchange professional; do not reply in anger.
Do not hold a useful change hostage to perfection
Google’s review standard emphasizes continuous improvement. If a change makes the code more maintainable, readable, and understandable, do not hold it up for days or weeks over perfection. Distinguish a material issue that must be resolved from improvements that can be considered without blocking the change.
Quick Recap
What should you check before posting a comment?
- Have I identified the exact line, behavior, or missing case?
- Have I explained the consequence or the standard behind the request?
- Is the requested action clear, while leaving room for a valid alternative?
- Have I labeled a nit or suggestion so it cannot be mistaken for a blocker?
- Am I commenting on the code rather than the person?
- Is there something specific and effective in the change that I should acknowledge?
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.
