Dictating Code Comments: A Developer's Honest Take

Nobody likes writing documentation in the moment. You're in the middle of a problem, you've just figured something out, and the last thing you want to do is stop and explain it in prose. So you don't. You ship the function with a vague name and tell yourself you'll comment it later.

You don't comment it later.

Voice dictation doesn't fix your intentions. But it does change the effort calculation enough that some developers, myself included, actually do the thing.

Why Comments Get Skipped

The friction isn't the thinking. You already know what the function does; you just wrote it. The friction is the switching. You have to move your hands from typing code to typing prose, shift your mental mode from syntax to English, and then shift back. For something that feels optional, that context switch is expensive enough to skip.

Dictation collapses that switch. You keep your hands on the keyboard or mouse for the code itself, then speak the comment. It takes maybe 10 seconds to describe what a function does out loud. The barrier goes from moderate to trivial.

What to Actually Dictate

Not everything needs a voice comment. Some things that do:

Why, not what. "This function sorts the array" adds nothing. "We sort here because the API returns unsorted results and downstream consumers expect order" is useful. The why is usually a sentence or two of reasoning that's obvious in your head right now and invisible to anyone reading this in six months, including you.

Edge cases you handled. If you wrote a conditional to catch a specific weird input, say so. Dictate a one-liner explaining what breaks without it.

TODO notes with context. Instead of // TODO fix this, speak a sentence. "TODO: this timeout value is hardcoded at 3000ms because the staging environment is slow; should be configurable before production."

Using VoiceInk in a Dev Environment

VoiceInk works in any text field, which means it works in VS Code, in terminal notes, in your wiki, in GitHub PR descriptions, anywhere your cursor lands. You don't run a separate app or switch contexts. Press the hotkey, speak, done.

For PR descriptions specifically, this changes the habit significantly. Writing a thorough PR description by typing feels like overhead. Dictating one while you still have the full context of the change in your head takes about 90 seconds and produces something your reviewer can actually use.

Voice for Technical Writing Beyond Code

The bigger opportunity for developers is probably documentation and internal notes, not inline comments. Architecture decision records, onboarding docs, runbook entries, these are almost always under-written because they take time that feels like it belongs to building, not explaining.

Dictation makes them faster to produce. You can speak an ADR faster than you can type it, and the conversational tone often lands better for human readers than formal prose anyway.

Some developers keep a daily note open and dictate into it throughout the day. "Spent an hour on the auth bug, the issue was that the token refresh wasn't accounting for timezone offsets, fixed in the middleware, need to add a test." That's 20 seconds spoken. It's a retrospective, a breadcrumb, and a reminder all at once.

The Real Argument

Documentation debt is technical debt. It compounds. The comment you skip today is the hour someone spends reverse-engineering that function next quarter, possibly you.

Voice dictation doesn't make you a more disciplined developer. It just removes enough friction that the disciplined choice becomes the easy choice. That's usually all behavior change needs.

If you've got a codebase with sparse comments and good intentions, try dictating your next three comment blocks instead of typing them. Time it. Then decide if the habit is worth keeping.