Dictating Code Comments: A Developer's Honest Review

Every developer knows they should write better comments. Most developers don't, not because they're lazy, but because stopping to type an explanation breaks the flow that took 20 minutes to build. Voice dictation doesn't fix the discipline problem, but it does fix the friction problem, and that turns out to matter more.

The Real Cost of Typing Mid-Flow

When you're deep in a function, your working memory is full. You know what the function does, why the edge case exists, what the variable names mean. All of that context lives in your head and evaporates within minutes of switching tasks.

Typing a comment forces a mode switch. You move from writing logic to writing prose, different mental gears. The comment comes out abbreviated because your brain is already trying to get back to the code.

Speaking a comment doesn't require the same context switch. You can keep your eyes on the code, press a key, say what you're looking at, and release. The comment appears. You're back in the function before the thought has cooled.

What Actually Works and What Doesn't

Dictation is excellent for inline comments explaining why something is written the way it is. "This timeout is set to 3 seconds instead of the default because the upstream API occasionally hangs on retry and we'd rather fail fast." That sentence takes four seconds to say. It would take 15 to 20 seconds to type, which is long enough to make you decide it's not worth it.

Dictation is also good for docstrings, README sections, and any documentation that lives outside the code itself. The more prose-like the writing, the more dictation helps.

Dictation is less useful for variable names, method signatures, and anything requiring precise punctuation or syntax. You wouldn't dictate a regex. You'd dictate the comment explaining what the regex does.

Setting It Up Without Disrupting Your Workflow

The key is having a dictation tool that works anywhere without requiring you to open a separate app or leave your editor. VoiceInk runs in the background on Mac and outputs transcribed text directly wherever your cursor is. In VS Code, in a terminal, in Notion, in Slack. Press a key to start, speak, release to stop. The text appears.

No cloud processing means no latency waiting for a round trip to a server. The transcription happens locally, which also matters if you're working on a codebase under NDA or dealing with sensitive infrastructure details.

The Documentation Problem Specifically

Documentation debt is real and it accumulates for one reason: writing docs is slower than writing code and it feels like it produces less. The ratio of effort to visible output is discouraging.

Voice changes that ratio. Talking through a module's purpose while you still have full context takes two minutes. Coming back to document it three weeks later takes 45 minutes of archaeology. The barrier to doing it in the moment is almost entirely about speed.

Some developers find it useful to record a short voice note after finishing a function, describing the decisions made and the tradeoffs considered. That note becomes the first draft of documentation. It captures the reasoning that would otherwise disappear.

An Honest Caveat

Dictation doesn't replace the thinking. If you're not sure what a piece of code does, speaking at it won't clarify anything. The value is in reducing the cost of externalizing thought you already have.

It also takes a few sessions to stop feeling self-conscious about narrating your own code. That feeling passes.

If your comments section is empty because typing mid-flow is too annoying, voice dictation is the fastest fix available. Try it on the next function you write and see whether the comment shows up.