Dictating Code Comments Without Losing Your Flow

Most developers write comments the same way they eat vegetables as kids: quickly, reluctantly, and only when someone is watching. It is not that they do not value documentation. It is that stopping to type prose in the middle of a coding session feels like pulling the handbrake.

Voice dictation does not fix every documentation problem, but it does fix that one.

The Context Switch Is the Real Cost

When you are deep in a function, your working memory is holding a lot. The shape of the problem, the edge cases, the reason you chose this approach over the obvious one. The moment you stop to write a comment, you shift from a technical mode to a writing mode. Your hands stay on the keyboard but your brain has to change gears.

For a lot of developers, that gear change is just expensive enough that they skip the comment and tell themselves they will add it later. Later never comes.

The value of voice here is not speed. It is continuity. You can keep your eyes on the code, keep your hands near the keyboard, and say out loud what you were already thinking. "This handles the case where the API returns a null user object, which happens when the session has expired but the cookie hasn't cleared yet." That sentence took four seconds to speak. It would have taken 30 seconds to type, and you would have opened a new mental thread to do it.

Where It Works Best

Not every part of a codebase benefits equally from voice documentation. The highest-value spots tend to be:

Function-level comments. When you finish writing a function, you already know exactly what it does and why. Dictating a quick explanation right then takes ten seconds and saves the next person (often future you) from reading the whole implementation.

Inline edge case notes. Any time you write code that handles something weird, say why. "Using setTimeout here because the DOM update hasn't completed synchronously" is the kind of note that saves an hour of debugging six months later.

README and setup instructions. These are pure prose. There is no reason to type them. Open the file, press your dictation key, and talk through the setup steps the way you would explain them to a new hire.

Commit messages. Short, clear, written in a hurry. Dictating them means you will actually write real messages instead of "fix stuff" or "wip".

A Practical Setup

The workflow is simple. Set up VoiceInk with a keyboard shortcut you can hit without looking, something on the function row or a corner key. When you finish a block of code and want to annotate it, tap the key, speak, tap it again. Your comment appears wherever your cursor was. No windows to switch, no app to open.

The transcription is fast enough that by the time you have looked back at your editor, the words are already there.

One adjustment worth making: speak in plain sentences, then clean up formatting in a second pass. Dictated comments read slightly differently than typed ones. They tend to be more conversational, which is usually a feature, not a bug. Comments that sound like a person explaining something are easier to read than comments that sound like technical specifications.

Documentation You Actually Write

The dirty secret of developer documentation is that most of it never gets written because writing it is unpleasant. It requires context switching, it slows you down, and it does not feel like real work in the moment even though everyone agrees it is valuable in retrospect.

Voice input does not make documentation glamorous. It just makes it fast enough to do in the moment, when the context is fresh and the explanation is obvious.

That is the only time good documentation actually gets written.

If you have a codebase with thin comments, try dictating notes for one session and see what you end up with.