Code Review Comment Templates for GitHub and GitLab: How to Write Feedback That Gets Acted On

Most code review comments that go nowhere have the same problems. The author can't tell whether the comment blocks the merge. They can't tell what the reviewer actually wants changed. Or the tone reads harsher than it was meant to, and the thread turns into a debate instead of a fix.

None of this takes talent to avoid. It takes a few habits. Here's the routine I use when I review pull requests, plus the small tools that make it faster.

1. Say how much the comment matters

The most useful thing you can add to a review comment is a label. Without one, the author has to guess whether "maybe rename this?" is a request or a passing thought, and careful authors treat every comment as blocking.

The Conventional Comments format (conventionalcomments.org) gives you a small vocabulary for this. A few labels cover most reviews:

• issue: something that needs to change before merging.
• suggestion: a concrete improvement you'd like but could live without.
• question: you don't understand something yet. No change implied.
• nitpick: trivial and optional, like naming or formatting.
• praise: something done well. Use it when it's true.

You can add a decoration like (non-blocking) or (blocking) to remove any doubt:

suggestion (non-blocking): This loop could use Array.some instead of tracking a flag. Fine to leave as is.

Even if your team never adopts the format officially, writing "Non-blocking:" or "Nit:" at the start of a comment does most of the work.

2. Make the comment self-contained

Write each comment so it makes sense to someone reading it in an email notification, without the surrounding thread. A good comment has three parts:

• What you noticed. Point at the specific line or behavior.
• Why it matters. A bug, a performance cost, a readability problem, a convention.
• What you'd do instead. Or, if you don't know, say that.

Instead of:

This is wrong.

Write:

issue: If user is null here (logged-out visitors hit this path), this throws before the redirect. Could we return early when there's no user?

The second version takes fifteen more seconds to write and saves a round trip.

3. Ask real questions, not rhetorical ones

"Why didn't you just use the existing helper?" sounds like a question but reads as an accusation. If you're genuinely asking, make it clear you might be missing context:

question: Is there a reason not to use formatDate from utils here? I may be missing a case it doesn't handle.

If you aren't asking, don't phrase it as a question. Make the suggestion directly.

4. Comment on the code, not the person

Small wording changes shift the tone a lot:

• "You forgot to handle errors" becomes "This call doesn't handle a failed request."
• "Your naming is confusing" becomes "I misread data2 as a copy of data. Something like filteredRows would help."
• "Why would you do it this way?" becomes "What led to this approach? I'd have expected X."

Using "we" and "this code" instead of "you" isn't about being soft. It keeps the discussion on what to change.

5. Use suggested changes for small fixes

If the fix is a line or two, don't describe it. On GitHub, the "Add a suggestion" button in a review comment inserts a suggestion block, and the author can apply it with one click. GitLab has the same idea with its "Insert suggestion" button. It's faster for both of you and leaves no room for misreading.

Save prose for things that need a decision: design, naming of public APIs, trade-offs.

6. Batch your comments into one review

Leaving comments one at a time sends a notification for each one, and the author may start fixing things before you've finished reading. On GitHub, use "Start a review" on your first comment instead of "Add single comment," then submit everything at once with a summary.

The summary is worth a few sentences:

Looks good overall. One blocking issue with the null user path in session.ts; the rest are suggestions and nits, so feel free to skip those. Happy to approve once the null case is handled.

That tells the author where to start and how far they are from done.

7. Keep reusable phrasing ready

You probably write some of the same comments every week: "Could you add a test for this case?", "Can we split this into a separate PR?", "Nit: unused import." A few ways to stop retyping them:

• GitHub saved replies. In your GitHub settings, under Saved replies, you can store canned responses and insert them from the comment box.
• macOS Text Replacements. In System Settings > Keyboard > Text Replacements, set short triggers like ;nb for "Non-blocking:" or ;test for "Could you add a test that covers this case?" They work in most Mac apps and text fields.
• A notes file with your team's review conventions, so new reviewers write comments the same way.

Templates handle fixed phrases well. Where they fall short is the part that's different every time: explaining a specific bug, or softening a comment you wrote while annoyed.

8. Reread before you submit

Before submitting, skim your own comments once with three questions:

1. Is it clear which comments block the merge?
2. Could the author act on each comment without asking me what I meant?
3. Would I be fine receiving this comment on my own code?

If a comment fails the third question, rewrite it. If it fails the second, add the "why" or a suggested change.

Where an AI writing tool can help

For the reread step and the writing in between, an AI writing tool can speed things up. The main thing to watch is where your text goes. Review comments often quote proprietary code, and many companies don't allow pasting that into a cloud chatbot.

I built DraftKey for this kind of writing. It's a Mac app that runs its model on your Mac, so your text isn't sent to a cloud AI service. As you type, it suggests the next words in gray and you press Tab to accept them. When you want to change something you already wrote, you tap Command+Option to open a rewrite panel with Fix writing, Shorter, Clearer, tone options like Friendly or Professional, or your own instruction. "Make this less blunt but keep the request" is a good one for review comments.

The honest details: it's $4.99 once for up to 3 Macs, it needs macOS 14 or later on Apple Silicon, and there's no free trial. It works in compatible Mac text fields, and some custom editors aren't supported, so how well it works in a given browser or editor depends on how that app exposes its text. It's at getdraftkey.com.

You don't need it to do anything in this article. The habits are what matter.

A quick checklist

• Label each comment: issue, suggestion, question, nitpick, or praise
• Say what, why, and what you'd do instead
• Ask real questions or make direct suggestions
• Talk about the code, not the person
• Use suggested changes for one- or two-line fixes
• Batch comments into one review with a short summary
• Keep saved replies or text replacements for repeated phrases
• Reread once before submitting

Try labeling your comments for a week. In my experience, it's the change that cuts the most back-and-forth.

Disclosure: I built DraftKey.