Dictating Code Comments Without Breaking Your Flow

Most developers write documentation the same way: reluctantly, after the fact, with less detail than they intended. It's not that they don't know it matters. It's that switching from writing code to writing prose breaks the rhythm. By the time you open a comment block and start typing an explanation, you've already started forgetting the decision you were about to document.

Voice input doesn't solve all of this. But it reduces the friction enough to change the behavior.

Where Voice Fits in a Dev Workflow

Dictating code itself is painful. Variable names, syntax, brackets, all of it fights against natural speech. Don't try it. That's not the use case.

But prose is different. Comments, docstrings, README sections, commit messages, internal notes, these are just writing. And writing is where speaking at 130 words per minute beats typing at 40.

The workflow that works: write the code, then without touching the keyboard for notes, move your cursor to the comment block and dictate the explanation while the logic is still fresh. Speaking it forces you to articulate what the code does in plain terms. If you can't explain it out loud in two sentences, that's useful information too.

Commit Messages Actually Worth Reading

Commit messages are a specific case where voice helps. Most developers type the minimum: "fix bug," "update styles," "wip." Not because they don't know what they changed, but because typing a real explanation feels like overhead when you just want to push and move on.

Speaking is faster than typing. A good commit message takes 15 seconds to dictate. It takes longer to type the same thing, and the activation energy feels higher. With something like VoiceInk, you press a key, say what actually changed and why, and it appears in your commit field. The barrier drops enough that the behavior changes.

README Sections and Internal Docs

These are where voice input pays off most. A README section that would take 20 minutes to type can be drafted in 6 by speaking. Yes, it needs editing. But you're editing instead of staring at a blank field trying to remember where to start.

The technique is the same as any dictation. Don't try to get it right on the first pass. Talk through what the function does, what parameters it takes, what it returns, what can go wrong. Then clean it up. The cleanup is fast when the raw material already exists.

Setting Up the Habit

The practical setup is simple. Get a tool that lets you dictate into any text field without switching apps. VoiceInk works this way on Mac: one hotkey, speak, done. You stay in your editor. You don't open a separate app or browser tab.

Then pick one type of writing to start with. Commit messages are a good choice because they're short and frequent. After two weeks of dictating commit messages, the motion becomes automatic. From there, adding comments and docstrings to the habit is a small step.

The Actual Payoff

Code gets read more than it gets written. The 30 seconds you spend explaining a function out loud will save future-you or a teammate ten minutes of reverse engineering. That math has always been true. The reason it doesn't change behavior is friction, not awareness.

Voice input makes documentation fast enough to compete with the pull of just moving on to the next thing. That's not a small change. For most developers, it's the difference between documentation that exists and documentation that doesn't.

If you write code, try dictating your next ten commit messages. See if the quality goes up when speaking is faster than justifying the typing effort.