How to Write Code Review Comments That Get Acted On

7 min read · Last updated: October 25, 2026

Code review comments get acted on when they are specific, explain the reason, say whether they block the merge, and focus on the code instead of the person. A good comment names the line, states the problem, proposes a fix, and carries a label such as nit, suggestion or issue.

Came here from Instagram, LinkedIn, X or YouTube? Here is the full source list you came for. Everything below is built from these, nothing else.

The standards

• Google Engineering Practices: How to write code review comments (accessed October 25, 2026)
• Google Engineering Practices: The speed of code reviews (accessed October 25, 2026)
• Conventional Comments specification (accessed October 25, 2026)

The platform docs

• GitHub Docs: Incorporating feedback in your pull request (accessed October 25, 2026)
• GitHub Docs: Reviewing proposed changes in a pull request (accessed October 25, 2026)
• GitLab Docs: Suggest changes (accessed October 25, 2026)

Key takeaways

• Label every comment. Google's guide uses Nit, Optional / Consider and FYI so authors know what is required.
• Comment on the code, not the developer. Frame the problem as a property of the code.
• Explain why when it helps: your intent, the best practice, or the code health gain.
• Use suggestion blocks for small fixes. One click applies them on GitHub and GitLab.
• Answer review requests within one business day at most, according to Google's guide.
• Leave at least one praise comment per review, as the Conventional Comments spec recommends.

This tutorial walks you through six steps and gives you templates you can paste into any pull request.

What you'll build

You will build a small, repeatable system for writing review feedback: a label vocabulary, a comment template, and a handful of saved replies. After this you will write comments that an author can read once and act on, without a follow-up chat to decode them.

The payoff is speed. Google's engineering guide says that "most complaints about the code review process are actually resolved by making the process faster." Unclear comments cause the extra round trips that make reviews slow.

What do you need before you start?

You need a pull request or merge request to practise on, on GitHub or GitLab. You also need your team to agree on one rule: what "blocking" means. If a comment must be fixed before merge, it is blocking. Everything else is optional unless the reviewer says otherwise.

Nothing to install. If you want a browser shortcut layer later, the Conventional Comments project lists an extension, but plain text works fine.

Step 1: Why does every comment need a label?

A label tells the author whether a comment is required or optional. Without one, authors treat every comment as mandatory, which wastes time, or treat all of them as optional, which lets real bugs through. Google's guide says labels "prevent them from treating every comment as mandatory."

Google recommends three labels for severity:

Label	Meaning	Must the author act?
Nit	A minor issue that should technically be fixed but has little impact	Usually yes, but low priority
Optional / Consider	A worthwhile idea that is not strictly required	No
FYI	Not expected in this change, but useful to consider later	No

The Conventional Comments spec goes further. Its format is <label> [decorations]: <subject>, followed by an optional discussion. Its recommended labels include praise, nitpick, suggestion, issue, todo, question, thought, chore and note. Its decorations are (non-blocking), (blocking) and (if-minor).

Pick one set and stick to it. Small teams do well with five: praise, nitpick, suggestion, issue, question.

Step 2: How do you write one comment the author can act on?

A comment the author can act on has four parts: a label, the specific problem, the reason, and a proposed fix. If any part is missing, the author must guess or ask. Use this template:

<label> (<blocking|non-blocking>): <what is wrong, in one sentence>

<why it matters>

<what you would do instead>

Here is a real-shaped example:

issue (blocking): This query runs once per item inside the loop.

With a few hundred items this becomes a few hundred round trips, and
the page will slow down as the list grows.

Could we fetch all the rows once before the loop and look them up
from a map?

Google's guide says you should explain your reasoning when it helps: "your intent, the best practice you're applying, or how the change improves code health." It adds that this is not required for every comment. A typo fix needs no essay.

Step 3: How do you give feedback without sounding harsh?

Comment on the code, not the developer. Google's guide says to "comment on the code and not on the developer" and to frame criticism as a property of the code, such as added complexity or lack of benefit, instead of a question about the author's choices.

Compare these two comments:

Sounds like blame	Sounds like a code observation
Why did you make this so complicated?	This function has four nested branches, which makes the happy path hard to follow.
You forgot to handle null.	This path can receive null when the user has no profile. What should happen there?
Don't do it this way.	This adds a second source of truth for the cart total. Could we derive it from the items?

The right column names the code, states the effect, and ends with a question or a proposal. It is also longer, and that is fine. Clear beats short.

Step 4: When should you ask, and when should you tell?

Ask when the author knows the code better than you. Tell when the fix is small and unambiguous. Google's guide says it is "the developer's responsibility to fix a CL, not the reviewer's", and that letting developers decide helps them learn and often produces better solutions because they know the code better.

It also says that direct instructions, suggestions or code can be more useful in some cases. A simple rule:

1. Design or approach problem: ask a question or describe the problem. Let the author pick the fix.
2. Small mechanical fix: write the exact change yourself.
3. You don't understand the code: say so. Google's guide says the author should usually rewrite the code to be clearer, not only explain it in the review tool.

Step 5: How do you use suggestion blocks on GitHub and GitLab?

Suggestion blocks put your exact fix in the comment, and the author applies it with one click. On GitHub, select the line, click the Suggestion icon in the comment box, and edit the text inside the block. GitLab uses the same idea with explicit line offsets.

On GitHub, the comment looks like this:

nitpick (non-blocking): Constant naming.

```suggestion
const MAX_RETRIES = 3;
```

On GitLab, the first line of the block carries the range. According to GitLab's documentation, -0+0 replaces only the commented line, and -2+2 replaces two lines above and two below:

suggestion: Use the shared constant.

```suggestion:-0+0
const MAX_RETRIES = 3;
```

The author can then apply suggestions one by one or batch them. Both platforms support batching so you get a single commit. GitHub's docs say each person who suggested a change becomes a co-author of that commit. GitLab limits a suggestion to 100 lines above and 100 below the commented line.

One caution: on GitHub, only people with write access can apply suggestions, and for fork pull requests the author must also have allowed edits from maintainers.

Step 6: Why should you praise and respond fast?

Praise tells the author what to keep doing, and speed keeps the review useful. Google's guide says to "point out what you liked" and explain why it is good, such as a cleaned-up algorithm or strong test coverage. The Conventional Comments spec recommends at least one praise per review and warns that false praise is damaging.

praise: Splitting the parser from the validator makes this much
easier to test. The new unit tests cover the edge cases well.

On speed, Google's guide sets "one business day" as the maximum time to respond to a review request. It says slow reviews hurt team velocity and "discourage code cleanups, refactorings, and further improvements."

What are the most common mistakes?

• Unlabelled comments. The author cannot tell a bug from a preference. Always label.
• Vague comments. "This is confusing" gives nothing to act on. Name the line and the reason.
• Personal framing. "You always..." invites defence. Talk about the code.
• Style debates in review. If a linter can catch it, automate it. Our Claude Code Ruff hook guide shows one way to keep formatting out of human review.
• Blocking on preferences. Mark preferences non-blocking so they do not stall the merge.
• Explaining only in the tool. Google's guide notes that explanations written only in the review tool do not help future readers of the code. Ask for a clearer name or a code comment instead.
• Rewriting the whole solution. Point at the problem. Let the author own the fix.

What should you do next?

1. Save the five labels and the comment template as snippets in your editor or as GitHub saved replies.
2. Agree with your team on what blocking means.
3. Try the suggestion block on your next small fix.
4. Review AI-written pull requests with the same discipline. Our guide on how to review AI-generated code covers what to look for.
5. Browse the VS Code extensions we recommend for faster in-editor review.

FAQ

What makes a good code review comment?

A good code review comment is specific, explains the reason, says whether it blocks the merge, and targets the code instead of the person. It should name the line, describe the problem, and suggest a fix or ask a clear question. A label like nit or issue removes guesswork.

What does "nit" mean in a code review?

In Google's engineering guide, a nit is a minor issue that should technically be fixed but has little impact. Reviewers prefix such comments with "Nit" so the author knows they are low priority. The Conventional Comments spec calls these nitpicks and treats them as minor, preference-based requests.

How fast should you respond to a code review?

Google's engineering guide says one business day is the maximum time to respond to a review request, ideally at a natural break in your work. The guide argues that slower reviews reduce team velocity and pressure reviewers to accept lower-quality changes.

How do you add a suggested change on GitHub?

Hover over the line in the pull request diff, click the blue comment icon, then click the Suggestion icon in the comment box. Edit the text in the inserted block and post it. The author can commit the suggestion directly if they agree.

Pick one pull request today and rewrite its three most vague comments using the template above. Then grab the free tools on Art of Code and see our AI code review guide for the next step.

Written by Adithya Guttha, Founder of Art of Code.