How to Stage Code Review Comments Before Submitting

A drive-by code review comment is one that the reviewer typed into the diff view while scrolling, without context, without re-reading the surrounding code, and without considering whether the comment is worth the author's time to address. These comments are usually nitpicks, often tone-deaf, and frequently wrong once the surrounding code is read. They are the dominant source of friction in code review. The pattern that produces them is the same pattern that produces every other kind of low-quality writing: typing into the place where the text will be published. The fix is to write review notes in a separate file first, then paste them into the diff view in one pass. This guide covers the staging workflow, the file structure, and the tone benefits.

For neighbouring topics, see Markdown READMEs: screenshots as files in /docs, the .env file should never touch history, and best clipboard habits for developers in 2026. For clipboard mechanics, see Windows clipboard settings, line by line.

Why drive-by comments happen

The diff view in GitHub, GitLab, and Azure DevOps is optimised for posting comments inline. A reviewer scrolls, sees a line that looks wrong, clicks the + icon next to the line, types a comment, and submits. The friction is low by design — it is what makes online code review fast — and the same low friction is what makes drive-by comments easy to post.

The alternative, which most senior reviewers default to, is to read the whole diff first, take notes, and then post the notes as comments in a second pass. This is slower in wall-clock time but faster in review cycles, because the comments are better-considered and the author does not have to push back on comments that the reviewer would have retracted on a second read.

The staging workflow formalises this. The reviewer writes notes in a file as they read, then converts the notes into posted comments at the end. The notes file is the buffer that catches the drive-by impulse.

The notes file

The notes file is a plain-text or Markdown file, usually per-PR, where the reviewer writes observations as they read. The structure that works:

# PR 1234: refactor auth middleware

## Overview
- Three files changed, ~400 LOC
- Refactor extracts token validation into a separate module
- Test coverage looks reasonable

## Comments

### src/auth/middleware.ts
- L23: the `validateToken` function name is generic. `validateBearerToken`?
- L45: this `try/catch` swallows the error. Log it?
- L67: the comment says "TODO: remove after rollout". When?

### tests/auth/middleware.test.ts
- L12: missing test for expired token
- L34: the mock setup is duplicated from test 3

## Summary
The refactor is sound. The main concern is error handling in `validateToken`. Two nits about naming and a TODO that needs a date.

The file is created at the start of the review and updated as the reviewer reads. The ## Comments section is the staging area; the ## Summary is the synthesis that goes into the PR's top-level comment.

The file lives in a notes directory (often ~/notes/reviews/ or a similar scratch location) and is not committed. The reviewer may keep it for a few days in case the author asks for clarification, then discards it.

Pasting comments into the diff view

Once the notes file is complete, the reviewer opens the diff view in a second pass and posts the comments. The mechanics:

• For each item in the ## Comments section, navigate to the line, click +, and paste the comment.
• Reviewers usually tweak the comment slightly when posting — adding the line context, softening the tone, or merging related items.
• The summary goes into the PR's top-level comment field.

The paste is a single action per comment, but the comment was written with the whole diff in mind. This is the deliberate difference from drive-by commenting: the comment has been considered in the context of the whole change, not just the line it is attached to.

Why the clipboard matters here

The clipboard is the transport between the notes file and the diff view. Each comment is a paragraph of text, copied from the notes file and pasted into the comment box. The Windows clipboard holds 25 items in history, which is usually enough for a PR with 10-20 comments. The reviewer can paste from Win+V history if they need to re-paste a comment they edited.

The risk: a notes file may contain text that should not be on the clipboard. A code review comment is not a secret, but if the reviewer is also looking at production logs or stack traces while reviewing, those artifacts can end up on the clipboard alongside the comments. The clipboard does not distinguish; Win+V shows everything.

The mitigation: keep the notes file free of secrets. If a comment references a log line, copy the log line into the notes file with sensitive fields redacted, not raw. This is the same redaction habit that applies to logs and stack traces. See copying error logs without taking half the console and stack traces, tokens, and the clipboard for the broader habit.

Tone benefits of staging

The tone difference between a drive-by comment and a staged comment is usually the most visible benefit. A drive-by comment tends to read as:

why is this a try/catch?

A staged comment, written with the whole diff in mind, tends to read as:

The try/catch at L45 swallows the error. If the intent is to fall through to the anonymous path on failure, that's fine, but logging the error would help debugging. If the intent is something else, can you clarify?

The second comment is longer, but it gives the author something to act on. The first comment makes the author guess what the reviewer wants.

Staging also catches duplicate comments. A reviewer who reads the whole diff first often notices that two lines they were about to comment on are actually the same pattern, and one comment that addresses the pattern is better than two comments on individual lines.

When staging is overkill

For a small PR (under 100 LOC, one file, one logical change), staging is overkill. The reviewer reads the diff once, posts one or two comments, and approves. The notes file adds overhead without benefit.

For a medium PR (100-500 LOC, multiple files), staging is worth it. The notes file catches drive-by impulses and produces a more coherent review.

For a large PR (over 500 LOC), staging is essential. A large PR reviewed without staging produces 30+ comments that the author has to triage, many of which contradict each other or address points that the reviewer would have retracted on a second read.

Tools that support staging

GitHub's own review interface supports a "pending comments" workflow that approximates staging. A reviewer posts comments as "pending" rather than "submitted", and the comments are visible only to the reviewer until they submit the review as a whole. This is a halfway house: the comments are still typed into the diff view, but they are not sent until the reviewer is ready.

The limitation of pending comments is that they are still typed inline, so the reviewer does not get the synthesis view that a notes file provides. The notes file shows all comments in one place, which makes it easier to spot duplicates, contradictions, and tone issues.

Some reviewers use a clipboard shelf to stage the comments. Each comment is a card; the cards are visible side by side; the reviewer reorders, edits, and merges before pasting them into the diff view. This is the same pattern that designers use for asset staging. For more on this pattern, see how to keep a repro command next to its screenshot and batching copies before you switch windows.

A workflow that minimises friction

The friction in staging is the file management: creating a notes file, naming it, finding it later. The pattern that minimises friction:

1. Use a template. A Markdown template with the ## Overview, ## Comments, ## Summary sections pre-filled saves the reviewer from staring at a blank file.
2. Name the file by PR number. pr-1234.md is findable later.
3. Keep the notes directory shallow. ~/notes/reviews/ with flat files is easier to scan than a nested structure.
4. Delete after the review closes. Notes files are scratch; they should not accumulate.

For reviewers who do this every day, a small shell function or VS Code snippet that creates a notes file from the PR URL saves a few seconds per review.

The paste-once discipline

The discipline that makes staging work is paste-once. The reviewer writes the comment once, in the notes file, and pastes it once into the diff view. They do not edit the comment in the diff view after pasting, except for minor tweaks. They do not re-type the comment in a Slack DM to the author. They do not paste it into a follow-up email.

The paste-once discipline is what prevents the comment from drifting. A comment that is typed in three places — the notes file, the diff view, and a Slack thread — will end up with three slightly different versions, and the author will be confused about which is canonical. The notes file is the source; the diff view is the publication; Slack is for follow-up discussion that references the published comment, not re-states it.

A short checklist

• Create a notes file at the start of the review, named by PR number.
• Write observations as you read, with line numbers.
• Read the notes file end-to-end before posting.
• Paste comments into the diff view in a second pass.
• Post the summary as the top-level review comment.
• Keep the notes file for a few days, then discard.

Background for this constraint is Binary Files on the Clipboard: Just Don't.

Related reading

• The .env File Should Never Touch History
• Binary Files on the Clipboard: Just Don't
• Best Clipboard Habits for Developers in 2026
• Clipboard Tools on Multi-Monitor Windows Setups

Sources

• GitHub Docs — Reviewing proposed changes in a pull request — official GitHub documentation for the pending-comments workflow that approximates staging inline
• GitLab Docs — Merge request reviews — official GitLab documentation for the merge request review workflow, including comment threads and pending comments
• Conventional Comments — GitHub project — a community standard for tagging review comments (issue:, nitpick:, question:, praise:) that pairs well with a staged notes file
• Microsoft Support — Using the clipboard on Windows — official statement of the 25-item history and the paste mechanics that the staging workflow relies on
• OWASP — Code Review Guide — reference for security-focused code review habits, including what should and should not be in review notes

Copy. Stack. Drop.

Transform your clipboard into an interactive edge shelf. Stack, pin, and drag assets into any app with zero friction.

Download for Windows Get from Microsoft Store

How to Install Guide · First 10 Minutes Guide · Drag & Drop Guide · Edge-Drop vs Win+V · Support