Pull Request Review Comment Templates

Code review comments get worse under load. The first review of the morning is thoughtful; by the fifth PR the comments shrink to "why?" or "change this" with no reasoning, and the author is left guessing whether it is a blocker or a nit. Most of a good review comment is structure — a clear severity, a specific reason, a suggested direction — and that structure is reusable. A small set of review comment templates lets you keep feedback clear and kind even when the queue is deep.

This guide gives you a starter set of comment templates and a way to drop them into a review without retyping the framing every time.

Why templated review comments read as more thoughtful, not less

A review comment fails when the author cannot tell what you mean or what to do. Severity is ambiguous ("is this blocking?"), the reason is implied ("obvious, surely?"), and the fix is unstated. A template carries the parts that are easy to drop under pressure — a severity tag, "here's why," "here's a direction" — and leaves you to fill the one specific observation. The comment ends up more considered than a rushed freeform line, because the courtesy is built in.

Consistent severity tags also reduce review friction across a team: when everyone marks blockers, suggestions, and nits the same way, authors stop over-reacting to nits and stop missing real blockers.

How do I reuse comment templates in a code review?

A code host's review comment box is a normal web text field, so a browser-based text expander can insert a framed comment:

1. Save each comment type as a snippet — //block, //suggest, //nit, //praise, //q.
2. Open the inline comment box on the line you are reviewing.
3. Type the trigger, and the framed comment appears.
4. Fill the one specific observation, then submit.

Because the snippets live in the browser, the same set works on whatever code host or review tool runs in your browser. SlashSnip inserts the text into the field you are typing in; it does not connect to your code host's API, post comments for you, or read the diff — it is a writing aid for the comment you are already writing.

A starter set of review comment templates

Five comment types cover most of what a review needs to say.

Blocker (//block)

**Blocking:** {cursor}

Why this matters: [correctness / security / data-loss / contract risk].

Suggested direction: [what would resolve it].

The {cursor} lands right after the severity so you state the issue first; naming why it blocks is what keeps a blocker from feeling arbitrary.

Suggestion, non-blocking (//suggest)

**Suggestion (non-blocking):** [observation].

You could [alternative]. Happy to merge as-is if you'd rather keep it — flagging for the next pass.

Marking it non-blocking explicitly is the whole value: it tells the author they can ship.

Nit (//nit)

**Nit:** [tiny style / naming / wording point]. Totally optional.

A nit labelled as a nit costs the author nothing to skip — and stops small comments from reading as demands.

Question, not a demand (//q)

**Question:** [what you're unsure about] — is [X] intentional here?

If yes, a one-line comment would help the next reader; if not, [the alternative].

Specific praise (//praise)

**Nice:** [the specific thing done well] — [why it's good]. Worth keeping as a pattern.

Praise that names the specific thing teaches the pattern; "LGTM" does not.

Use variables where they help

Review comments need fewer variables than email, but two earn their place:

• {{clipboard}} drops in a line, a doc link, or a code reference you just copied.
• {cursor} marks where you start typing after the comment expands.

{{date}} and {{time}} are available too if you log review notes elsewhere. The smart variables reference has the syntax. Many review fields support Markdown, so the **bold** severity tags above render as intended — but verify on your host before relying on it, since a few use a custom editor.

Keep the set small and never auto-fill the substance

Two rules keep review templates useful:

• Cap the set at five to six comment types. Block, suggest, nit, question, praise covers the range.
• Template the framing, never the observation. The snippet carries severity and tone; the specific thing about this line is always typed by you. A template that fills in the reasoning would just produce confident, generic noise.

For the structural side of review — what to check, not how to phrase it — the code review checklist snippets guide and the review-prompt snippets guide cover adjacent ground. A practical limit to note: each reviewer's snippets live in their own browser, with no shared library or cloud sync yet, so a team keeps comment conventions consistent by agreeing on triggers and passing the snippet text along.

Next steps

Save the blocker and the nit templates first — they are the two whose ambiguity causes the most back-and-forth — then add the rest. SlashSnip for developers shows where browser snippets fit an engineering workflow, and the plan overview covers the free tier.