Code review with video: when a walkthrough beats another comment

Most review comments should stay written. A few conversations, usually a reviewer's concern about the whole approach, go much better as three minutes of talking through the code instead.

By the VeoRec team · Oct 3, 2026 · 11 min read

Code review with video sounds like a gimmick until you have spent forty minutes typing a comment about why a new caching layer worries you, deleted it, and typed it again. Some review conversations are mostly about context: what the author was thinking, how the pieces fit, why one approach beats another. Text handles that badly. A three-minute recording handles it well.

Most review feedback should stay written, and this post argues for that as hard as for the video. What follows is written mainly from the reviewer's chair: where a recorded reply earns its place, how to structure one so it lands as help rather than criticism, and the one habit that stops important decisions from living only inside a video file. Any recorder will do; where the mechanics matter, we note how VeoRec, a screen recorder for developers, handles them.

Video fixes the understanding problem, not the nitpick problem

When researchers at Microsoft studied how review actually works, they found that finding defects was the main stated motivation, but that understanding the code and the change was the key aspect of the work, and that developers used a wide range of tricks to get that understanding, most of which their tools did not support (Bacchelli and Bird, 2013). Knowledge transfer and team awareness turned up as benefits of review too.

A diff shows you what changed, line by line, in alphabetical file order. It does not show you which file matters most, what the author tried first, or how the change behaves when you run it. An author talking over the diff for three minutes answers those questions before the reviewer has to ask them.

What video does not fix: specific line-level feedback. "This loop is off by one" belongs on the line, in writing, where the author can click it, fix it and resolve it. Nobody wants to scrub through a recording to find which variable you meant.

When a review video helps and when it wastes everyone's time

The test is simple: would you otherwise schedule a call, or write more than about five paragraphs? If yes, a short recording is probably cheaper for both sides. If the feedback fits in one or two sentences on a line, type it.

If you are unsure, the scorecard below gives a quick verdict for the review in front of you. Tick what applies.

Across time zones, a video can save a whole day

Google's guide sets one business day as the longest a reviewer should take to respond (source). That is reasonable inside one office. Across an eight- or nine-hour gap, every clarifying question costs a full day: the reviewer asks in their afternoon, the author answers the next morning their time, and the reviewer only sees the answer when their own next day starts.

A recording removes most of those questions before they are asked, in either direction: an author's walkthrough up front, or a reviewer's reply that explains the concern in full instead of opening with a one-line "why not X?" that needs a day to come back. For a team split between, say, Berlin and San Francisco, cutting one question-and-answer cycle out of a review is the difference between merging on Tuesday and merging on Thursday.

Ask authors for a walkthrough on large changes

This post is about the reviewer's side, but the author's side changes what lands in your queue. A large or visual pull request that arrives with a three-minute walkthrough (why the change exists, a demo, the most important file, the risky part and what the author wants from the review) turns a cold read into a guided one: you still read every line, but you read them knowing what each part is for. As a reviewer, it is fair to ask for one when a change touches a dozen files and comes with a two-line description. Authors will find the structure, with timings and an example script, in how to explain a pull request with video.

Reviewers: reply with video when the feedback is about the approach

The other direction is less common and often more useful. When a reviewer has a concern about the overall design, typed feedback tends to go wrong in two ways: it gets long and dense, or it gets short and sounds harsher than intended. "Why not just use the existing queue?" reads very differently from the same sentence said with a curious tone while pointing at the queue in question.

A reviewer reply video works well for:

• Alternative approaches. Open the existing code you think the author should reuse and show how it would fit. Sketching in the editor beats describing in prose.
• Questions that might be your misunderstanding. Talking through your reading of the code ("here is what I think happens when the token expires") lets the author spot exactly where your model diverges from theirs.
• Mentoring. Explaining why a pattern causes trouble later, with an example from elsewhere in the codebase, is teaching. Teaching lands better spoken.
• A summary of many small comments. If you left 15 line comments, a one-minute video that says "three of these matter, the rest are nits" helps the author prioritise.

The guide on writing review comments recommends labelling severity so authors know what is required: prefixes like Nit, Optional and FYI. Do the same out loud. "This next one is optional, take it or leave it" is one sentence and removes a lot of anxiety for the author.

Comment on the code, never on the person. Out loud, that rule is easier to keep: you can hear when you sound annoyed, and you can record again.

Structure every review video the same way

Whether you are the author or the reviewer, a predictable structure makes videos faster to record and faster to watch. People learn where to skip to. A shape that works for both roles:

1. One sentence of context. "This is my review of the batch pricing change, mostly about the retry logic."
2. The main point first. The thing you would say if you only had 30 seconds.
3. Evidence on screen. The code, the running app, the failing case. Point with the cursor or select the lines you are talking about so viewers know where to look.
4. Smaller points, clearly labelled. Say which ones block the merge and which are suggestions.
5. The ask. What should happen next: "If you agree, split the retry into its own function and I will approve."

Chapter markers help a lot here. If you drop a marker each time you move to a new point, the viewer gets a clickable list instead of a progress bar. In VeoRec you press M while recording and name the markers on the finish screen; the guide to chapter markers covers how viewers use them. A three-point review video might look like this:

Decide what goes in the video and what goes in writing

The rule that keeps video review from turning into a mess: the video carries the explanation, the text carries the record. Pull requests are read for years through git blame and code archaeology, and nobody doing archaeology will watch a recording. Google's guide says the same about live conversations: if you resolve something face to face or on a call, write the outcome on the change for future readers (source). A recording is no different.

In practice this means two habits. Authors put the video link at the top of the description, but write the description as if the video did not exist. Reviewers post their video with a short written summary underneath: "Video below. Summary: the retry can double-charge; please route it through the idempotency helper. Everything else is optional."

A transcript helps too. If your recordings are transcribed automatically, you can copy the exact sentence you said into the written summary instead of paraphrasing from memory, and anyone can search what was said across recordings later. More on that in searchable video transcripts.

Make the code readable before you hit record

A review video where nobody can read the code is worse than no video. The defaults on most developer machines (small font, high-resolution screen, a dark theme with dim comments) produce a recording where code turns into grey fuzz once it is scaled down to fit a pull request page.

The quick fixes:

• Zoom the editor two or three steps before recording. In VS Code that is Ctrl and = (Cmd and = on a Mac). Code you can read comfortably from arm's length will survive scaling.
• Record the editor window instead of a huge monitor, so the code fills more of the frame.
• Close the sidebar, the minimap and unrelated tabs. Fewer things on screen means bigger things on screen.
• Close the terminal that has your .env open. Then check for anything else that should not be in a shared video.

The full set of settings, with the arithmetic on how small your font really ends up, is in how to record your IDE and terminal.

Templates for review videos and the comments around them

These are starting points for the written parts that go with a video. Copy them into your pull request template or your team's review guide and adjust the wording to sound like your team.

Mistakes that make review videos worse than text

Teams that try video in review and give up usually hit one of these:

• Reading the diff aloud. "Here I added a parameter, here I renamed a variable." The reviewer can see that. Talk about why, and skip what is obvious.
• Twelve-minute recordings. Long videos get skipped or watched at double speed with half attention. If you cannot say it in five minutes, split the change or split the video. The post on how long a work video should be has numbers by purpose.
• Recording before the code is ready. If the pull request changes a lot after review starts, the video now describes code that no longer exists. Record when the change is ready for review, and re-record (it only takes three minutes) if the approach changes.
• Decisions that only exist in the video. Six months later, someone asks why the retry works this way. The answer should be in the pull request, not at 2:47 of a recording that may have been deleted.
• Using video to avoid a conversation. If you and the author disagree after two rounds, talk live. A recorded monologue in reply to a recorded monologue is just a slower argument.
• Making it mandatory for every change. A video for a one-line fix trains people to ignore videos.

Where the tool matters and where it does not

Any screen recorder works for this, but a few things make a real difference for review specifically. You want the link ready the moment you stop, so recording does not become a separate chore. You want viewers to be able to watch without creating an account, because your reviewer may be a contractor or someone from another team. And you want feedback tied to a moment in the video, so "at 1:40 you said the cache is per user, but it looks global to me" is a click, not a sentence.

VeoRec covers those: the recording uploads while you talk and the share link is copied when you stop, viewers need no account, and comments are timestamped with threaded replies that can be marked resolved, which maps well onto how review threads already work. If you want to see the comment flow before trying it, here is a small demo:

Where the tool does not matter: the structure, the length, and the habit of writing decisions down. A team with a basic recorder and good habits will get more out of this than a team with every feature and twelve-minute videos.

Answer your next design concern with a recording Open the code, talk through the concern in under four minutes, and post the link above a short written summary. The Free plan covers recordings up to 10 minutes. See VeoRec for developers

What to do on your next review

Do not roll this out as a process. Try it on one review and see whether the conversation goes faster.

1. Wait for the next review where your comment on the approach runs past three paragraphs.
2. Stop typing. Open the code you are worried about and, if you have one, the code you would reuse instead.
3. Record a reply in the shape above: context, main point, evidence, labelled smaller points, the ask. Stop at four minutes.
4. Post it with a three-line written summary: what blocks the merge, what is optional, what you need before approving.
5. Afterwards, ask the author one question: was the video clearer than the comment would have been? Adjust from there.

If you author more than you review, the reverse works too: record a three-minute walkthrough before you request review, write the description as if the video did not exist, and see how many "what is this for?" comments disappear.