Dictating Code Comments Without Breaking Your Flow

Every developer knows the comment that never got written. You understood exactly why that function worked the way it did, right up until the moment you moved on to the next problem. Three weeks later, neither you nor anyone else can reconstruct the reasoning.

The issue is not laziness. It is friction. Writing a comment requires switching modes, reaching for words while your brain is still mid-logic. Voice capture removes that switch.

Why Developers Skip Documentation

Code comments and documentation sit at the end of every task, which means they absorb whatever energy is left after the actual problem is solved. That is rarely much. When you have just spent two hours tracking down a race condition, writing a paragraph about it is the last thing you want to do.

The other problem is that typing a comment feels like going backward. You stop, you switch to a text field, you write a sentence or two that never quite captures the thing you understood five minutes ago, and then you return to the code. The comment exists but it is already a pale version of the real explanation.

Speaking the Reasoning While It Is Fresh

Voice is fast enough to capture thinking while you are still in it. Before you close a function you just fixed, before you push a commit, you can say in thirty seconds what you would spend five minutes trying to type later, or skip entirely.

With VoiceInk on a Mac, the flow is simple. Hold the key, say what the code does and why, release. The text lands wherever your cursor is, whether that is a comment block, a README, a Notion page, or a scratchpad. No context switch to a separate app, no recording to transcribe later.

The comment you dictate in the moment is almost always better than the one you write from memory an hour later.

What This Looks Like in Practice

Here is a concrete example. You write a caching layer with a specific expiration logic that is not obvious from the code alone. The reasoning involves a tradeoff you made between freshness and performance under a particular load pattern.

Typed comment: // cache expires after 90s for performance

Dictated comment, captured right after solving it: This uses a 90-second TTL instead of the more intuitive 30-second default because under peak load the upstream API starts throttling at roughly 40 requests per minute. Longer TTL reduces call frequency enough to stay under that ceiling. Revisit if the API rate limit changes.

The second version takes about fifteen seconds to say. It would take three to four minutes to type, and most people would not bother.

Beyond Comments: Voice-Driven Note-Taking

The same approach works for anything that requires capturing reasoning without stopping work. Architecture decisions, debugging notes, questions to revisit, ideas for refactoring, these all benefit from the low-friction capture that voice allows.

Developers who use voice for note-taking often keep a daily scratchpad open and drop observations into it throughout the day. A two-sentence dictation about a weird edge case you noticed costs almost nothing in the moment. Finding out a month later that you knew about it and never wrote it down costs much more.

Getting Started Without Disrupting Your Setup

You do not need to rethink your workflow to try this. Pick one category of writing, daily standup notes, PR descriptions, or comment blocks, and dictate those for two weeks. Keep everything else the same.

PR descriptions are a good starting point because the context is fresh right after you finish the work, you know what changed and why, and writing them is almost universally dreaded. Talking through one takes a minute. Reading one that was clearly written that way is noticeably better than the two-line placeholder.

The goal is not to voice-code your entire day. It is to stop losing the explanations that only exist in your head while you are deep in a problem. Those are worth capturing, and talking is the fastest way to do it.