Dictating Code Comments and Docs: A Developer's Guide

Every developer knows documentation matters. Most developers also know they are not writing enough of it. The reason is rarely ignorance or laziness. It is friction. After an hour of hard thinking to get a function working, the idea of switching mental gears to explain it in prose feels like running a second race after finishing the first.

Voice changes that equation in a specific way.

Why Docs Get Skipped

Writing documentation requires a context switch. You go from code-brain, which is precise, symbolic, and structured, to prose-brain, which is discursive and explanatory. Doing that switch with your hands still on the keyboard creates a strange in-between state where neither mode feels natural.

The result is one-line comments that explain what the code does rather than why, README files that are three months out of date, and function signatures that only make sense if you wrote them yourself.

Speaking the explanation out loud short-circuits this problem. You already know how to explain your code verbally. You do it in standups, in code reviews, in Slack. Dictation just captures what you would have said anyway.

What to Dictate and When

The highest-value moments for voice in a development workflow are:

Right after you finish a function. You still have the full context loaded. Speak a two-sentence explanation of what it does, what inputs it expects, and any edge cases that matter. Takes thirty seconds. Saves the next person twenty minutes.

During a code review. If you're leaving feedback, dictate your comments instead of typing them. Your verbal explanations tend to be more natural and complete than your typed ones, and review comments are exactly the kind of medium-length prose that benefits from speaking.

When you hit a dead end and need to think out loud. Rubber duck debugging by actually talking, with VoiceInk capturing what you say into a scratch note, often surfaces the problem faster than staring at the screen. You explain it and hear the gap.

For README updates. Open the file, put your cursor in the relevant section, and speak the update as if you're explaining it to a new team member. Edit it once. Done.

Practical Setup for Dictating Into Your Editor

VoiceInk works directly in any Mac app, including VS Code, Xcode, and terminal-based editors. You don't need a plugin or integration. Place your cursor inside a comment block or a markdown file, press the hotkey, speak, and the text appears.

For multi-line comments, start with the block syntax already open. Speak in complete sentences. The transcription handles punctuation reasonably well with natural speech patterns, though you may want to say "period" explicitly when ending a sentence if you find the model missing them.

Keep a scratch markdown file open as a notes buffer. Any time a thought arises about architecture, a decision you made, or a question you need to revisit, dictate it there without breaking your flow. Review it at end of day and move relevant parts into actual docs.

The Compounding Return

The reason to build this habit is not the five minutes you save writing a comment today. It is what happens six months from now when you or a colleague revisits code that is actually documented, with real explanations of the decisions that were made, not just what the code does but why it does it that way.

That kind of documentation almost never exists because it requires too much effort relative to the immediate reward. Dictating removes most of that effort.

Thirty seconds of explanation spoken immediately after writing a function is worth more than two hours of documentation written three weeks later from memory.

A Low-Risk Place to Start

Pick one pull request this week. Before you open it for review, dictate a summary of what changed and why. Paste it into the PR description.

See if your reviewers notice. See if future-you, reading the git history, is grateful.

Documentation does not have to be a separate project. It can be what happens when you stop keeping explanations inside your head.