How to Dictate Code Comments Without Losing Your Mind

Most developers write terrible documentation. Not because they're bad at writing, but because writing it is slow, thankless, and happens at the end of a long session when mental energy is gone. You know what you should write. You just don't want to type it.

Dictation won't fix your motivation, but it removes the friction that turns "I should document this" into "I'll do it later."

What Works and What Doesn't

Be direct about the limits up front. You should not dictate code itself. Variable names, function signatures, syntax, anything where a single wrong character breaks things, stay on the keyboard. Voice recognition has gotten good, but not "trust it with your production codebase" good.

What you should dictate is everything around the code. Comments explaining why a function exists. README sections. Internal documentation. Ticket descriptions. Architecture notes. Changelogs. Post-mortems. Anything prose-shaped is fair game.

This is actually most of the writing developers do. And it's the writing that gets skipped most often, because it requires context-switching from code-brain to writing-brain while your hands are still on the keyboard.

The Context-Switch Is the Real Problem

When you finish a function and need to write the docstring, you have all the relevant context in your head right now. You know why you made the tradeoffs you made. You know what edge cases exist. You know what the next developer needs to understand.

But opening a separate document, or even shifting to a comment block, breaks the flow. The writing gets deferred. The context fades. The comment eventually reads "handles edge cases" and tells nobody anything useful.

Dictating the comment while the code is still fresh sidesteps this. With a tool like VoiceInk, you press a key, speak the explanation you'd give a colleague, and it appears. You don't move your hands off the keyboard for longer than a breath.

A Practical Workflow

Here's how this looks in practice. Write the function. When it's working, don't immediately move on. Speak the comment as if explaining to a teammate: what this function does, why it exists, what it expects, what callers should know.

Spoken explanations tend to be more useful than typed ones. When you speak, you explain. When you type, you describe. There's a difference. "Returns user object or null" is a description. "Returns null instead of throwing because the calling context handles missing users gracefully" is an explanation.

For longer documentation, keep a running notes file open during development. When you solve something tricky, speak a sentence about what the problem was and how you fixed it. Five seconds now saves thirty minutes when you're writing the post-mortem later.

README Sections and Internal Docs

These are where dictation pays off most clearly. Developers avoid writing READMEs because it means leaving the editor, opening a markdown file, and doing actual writing. The cognitive distance feels large.

Try this instead. Set up a scratch document beside your editor. At the end of a session, dictate a paragraph about what you built and why. Don't edit it. Just capture. At the end of the week, you have raw material for documentation instead of a blank page.

The editing pass is fast because the thinking is already done. You spoke it out when the context was live. Now you're just shaping text that already exists.

Dictating Ticket Descriptions and PR Notes

These are pure prose, written under time pressure, often poorly. Dictate them. Your PR description should explain why you made the change, not just what changed. Speaking that explanation is faster than typing it and you'll write more of it, which means fewer back-and-forth questions from reviewers.

The keyboard stays essential for the hard parts of your job. Dictation handles the parts you've been skipping. That's a reasonable division of labor, and your future self, reading coherent documentation six months from now, will notice the difference.