How to Dictate Code Comments Without Breaking Your Flow

Ask most developers why their code is under-documented and the answer is usually some version of the same thing: it breaks the flow. You're deep in a function, tracking three variables and a side effect, and stopping to write a comment means context-switching into prose-writing mode. The comment doesn't get written. The next developer, often future you, pays for it.

Voice input changes the economics of that decision.

The Cost of Context Switching Is Real

Writing a comment by hand means stopping what you're doing, moving to the comment line, typing a sentence or two, and then re-entering the mental state you just left. For a small comment that takes 20 seconds to type, the actual cost is closer to two minutes once you account for re-entry time.

When the cost is that high, the brain finds reasons to skip it. The code is clear enough. You'll remember. Someone else will figure it out. These are all rationalizations for a friction problem.

If you can speak the comment in five seconds without lifting your hands from the keyboard position, the calculus changes. The comment is no longer a context break. It's a breath between thoughts.

What This Looks Like in Practice

With VoiceInk running on your Mac, you press a configurable key, speak your comment, and the text appears at the cursor. No mode change, no switching apps, no mouse movement. You stay in your editor.

A typical inline comment takes three to eight seconds to dictate. A function-level docstring explaining parameters and return values might take 30 seconds. Compare that to typing the same content, factoring in the pause to think about phrasing while your fingers wait. Speaking is almost always faster for prose-length text.

The workflow looks like this: write a function, position your cursor at the comment line, speak the explanation, and move on. The comment exists. You didn't break focus to create it.

Documentation Outside the Editor

Comments are only part of the documentation problem. There's also the README that never gets updated, the internal wiki page that's six months stale, the Confluence doc that was supposed to explain the deployment process.

All of that is prose. All of it is faster to dictate than to type. A developer who dictates a three-paragraph explanation of a service's architecture is doing something that rarely happens when the only option is sitting down to type it out.

Voice input lowers the activation energy for documentation tasks that never feel urgent enough to prioritize. If it takes five minutes instead of 20, it fits between other tasks instead of being deferred to a sprint that never comes.

Dictating Commit Messages and PR Descriptions

Commit messages are another place where most developers take shortcuts they later regret. A voice-dictated commit message takes the same time as typing a lazy one-liner, but you can actually include the why, not just the what.

Pull request descriptions are longer and benefit even more. Dictating a summary of what changed, why it changed, and what to look at during review takes two minutes by voice. It takes five to ten by typing, assuming you bother at all.

Teams that review each other's code know the difference between a PR with context and one without. Voice input makes it easier to be the developer who provides that context.

One Adjustment to Expect

Dictating in a technical context means your transcription tool needs to handle terms like variable names, function names, and jargon. VoiceInk handles most of this well, but you'll still want to review technical names after dictating. Proper nouns and camelCase terms occasionally need a manual correction. That's a reasonable tradeoff for the volume of text you get in return.

The editing overhead is small. The documentation gap it closes is not.

If your comments section is consistently empty, the problem might not be discipline. Try speaking the next one and see if the friction was the real issue all along.