Dictating Code Comments: A Developer's Honest Review

Nobody wants to write documentation. This isn't laziness. It's that switching from writing code to writing prose requires a gear change that feels expensive in the middle of a focused session. So the comment block stays empty, or gets a two-word placeholder, and the next developer inherits the confusion.

Voice dictation doesn't fix the motivation problem. But it fixes the friction problem, which is most of the problem.

Where Dictation Actually Helps in a Dev Workflow

The sweet spot isn't writing functions. It's annotating them after the fact. You've just finished a gnarly bit of logic and you understand exactly what it does and why. That clarity fades fast. Dictating a quick explanation while it's fresh takes about 30 seconds and produces a paragraph that would have taken five minutes to type.

Same with commit messages. The average commit message is a crime against future-you. Dictating a sentence or two about what changed and why costs almost no time when you're not hunting for keys.

Meeting notes after a sprint planning session, quick documentation on an internal API, a README that actually explains the project. All of these are bottlenecked by the typing cost more than the thinking cost.

Setting It Up Without Breaking Your Flow

The key is having dictation activate without leaving your editor. With VoiceInk, you hold a key, speak, and the text appears wherever your cursor is sitting. That means you can be in VS Code, place your cursor in a comment block, and dictate directly into it. No alt-tabbing to another app, no copy-pasting.

For most inline comments, this is faster than typing even if you're a 90-word-per-minute typist, because you're not context-switching out of your mental model of the code.

What Dictation Is Not Good For

Being honest here: dictating actual code syntax is mostly painful. Variable names, method chaining, brackets and semicolons, these don't come out well when spoken. Voice coding tools exist and are impressive, but they have a learning curve and a different purpose.

This article isn't about replacing typing with voice for code itself. It's about the prose that lives around the code, and that part works very well.

Also, open-plan offices create an obvious problem. Dictating in a room full of colleagues either requires headphones and a quiet voice or a private space. Remote workers and people with private offices have an advantage here.

A Real Scenario

You've written a caching function with some non-obvious expiry logic. It works. You know why every decision was made. You need to document it.

Typing the comment: you open the block, think about how to start, write a sentence, delete it, write another, glance back at the code, write three more sentences, read it back, revise. Four minutes, maybe five.

Dictating the comment: you hit your key and say, out loud, "This function caches API responses for 90 seconds. The short TTL is intentional because the upstream data updates frequently and stale reads caused the bug in issue 412. Don't increase it without checking with the data team first." Done. Clean, contextual, useful. Thirty seconds.

That's the actual value proposition. Not speed for its own sake. Speed for the tasks where speed is the only thing stopping you from doing them at all.

The Habit Worth Building

Try annotating your work verbally for one week. Every time you finish a function, a class, or a tricky block of logic, dictate a brief explanation before moving on. Treat it like leaving a note for the next person, because you are, even if that person is you in three months.

The code you write with good documentation around it is different code. You make better decisions when you know you have to explain them. That's a side effect worth having.

If you've been meaning to document better but never quite manage it, reducing the friction is a good place to start.