Dictating Code Comments: A Developer's Practical Guide

Good code comments are not about what the code does. Any developer can read the code. Comments are for why: why this approach, why this tradeoff, why this number and not another. That kind of explanation is essentially prose, and prose is faster to speak than to type.

The Comment Problem

Most developers undercomment not because they do not know what to write, but because writing it feels expensive in the moment. You are in a flow state, you have just solved something, and stopping to type three paragraphs explaining your reasoning breaks the rhythm in a way that feels like it costs more than it is worth.

This is a reasonable feeling based on a bad input method. Speaking three paragraphs takes about ninety seconds. Typing them takes four or five minutes, minimum, and that is if you are not second-guessing your word choices.

Voice dictation changes the math.

What to Dictate and What to Type

Not everything benefits from voice. Code itself is faster to type or autocomplete. Short inline comments, maybe one sentence, are fine either way. The cases where dictation wins clearly are:

• Function and method docstrings that need to explain context or constraints
• README sections and internal documentation
• Architecture decision records
• Commit messages longer than one line
• Pull request descriptions
• Notes in a personal dev journal or second brain

Anything where you need to explain your thinking in full sentences is a good candidate. That covers more of your day than you might expect.

Setting Up a Workflow That Does Not Break Flow

The key is making dictation fast to start. If activating voice input requires three clicks and a menu, you will not use it when it matters.

VoiceInk uses a single keystroke to start recording. Press the key, speak, release. The transcribed text appears wherever your cursor is, whether that is a comment block in VS Code, a Notion doc, or a GitHub PR. No context switching, no separate app to manage.

A practical workflow: write the code, then before moving to the next function, press the shortcut and explain what you just did and why. It takes ninety seconds. It saves the next developer, who might be you in three months, twenty minutes of archaeology.

Dictating Documentation at Scale

If you write internal documentation, the speed advantage compounds quickly. A page of documentation that would take forty-five minutes to type can be spoken in fifteen. That is not a small difference across a week of writing docs.

The spoken draft will need cleanup. Technical documentation requires precision, and precision requires editing. But editing a spoken draft is faster than writing from scratch, and far better than having no documentation at all, which is what happens when the process is too slow to sustain.

Some developers find it useful to speak documentation while the code is still fresh, immediately after writing a module or finishing a feature. The knowledge is at the surface. Speaking it down before context-switching preserves detail that typing later would flatten or lose.

On Accuracy With Technical Terms

The honest concern: voice recognition and technical vocabulary have a complicated history. Transcribing "idempotent" or a specific library name is not the same as transcribing plain prose.

Modern local models handle common technical terms well. Less common terms will occasionally require manual correction. The correction rate is low enough that the speed gain still holds, but it is worth knowing that dictating the word "asynchronous" will go fine and dictating an obscure internal API name might not.

For proper nouns and internal terminology, a quick manual fix takes two seconds. Factor that in and dictation still wins on time.

If your documentation and comments are sparse because writing them is slow, voice dictation is the most direct fix available. Try it on the next function you write.