Dictating Code Comments and Docs: A Developer's Honest Guide

Documentation debt is real and it accumulates fast. Most developers know exactly why their function works the way it does, right when they write it. Six months later, that context is gone. The code remains, silent and unexplained.

The reason docs don't get written isn't laziness. It's friction. After hours of precise, syntactically exact typing, sitting down to write a paragraph of prose in plain English feels like switching sports mid-game.

Voice dictation removes a lot of that friction.

Where Voice Fits in a Developer Workflow

Voice is not for writing code. Don't try to dictate a function. Syntax is too precise, variable names are too specific, and the error rate on exact strings makes it more trouble than it's worth.

Voice is for everything around the code. That's actually a lot:

• Inline comments explaining why, not just what
• README sections describing setup and intent
• Commit messages that say more than "fix bug"
• Meeting notes and decision logs
• Slack or email replies to teammates about technical context
• Architecture notes you take while thinking through a problem

Anything that would be written in natural language is a candidate.

The Commit Message Problem

Most commit messages are terrible because writing a good one requires stopping, context-switching to prose mode, and typing a few coherent sentences right when you want to move on to the next task.

With voice, you finish your commit, press a key, and say out loud what you just did and why. Thirty seconds. The result is a message that actually helps future-you understand what past-you was thinking.

This is the kind of small improvement that compounds. One clear commit message is nothing. Twelve months of clear commit messages is a meaningful record of how a codebase evolved.

Inline Comments You'll Actually Write

The standard advice is to write comments explaining why the code does something, not what it does. Good advice, rarely followed, because writing a "why" comment takes more cognitive effort than writing a "what" comment.

Speaking that explanation is easier. When you finish a tricky block, just say it out loud: "This retry loop caps at five attempts because the upstream API starts rate-limiting after the fourth, and we saw failures in production when we didn't account for that." That's a comment worth having. It took ten seconds to say.

With a tool like VoiceInk running in the background, you can have that text appear directly in your editor. Say it, check it, paste or accept it. No context switch to a separate app.

Capturing Architecture Thinking in Real Time

Some of the most valuable documentation never gets written because it exists only during the thinking phase, before the decision is made, when you're weighing tradeoffs. By the time the decision is finalized, the reasoning feels obvious and not worth writing down.

If you can speak while you think, you can capture that reasoning cheaply. Open a notes file, dictate your thinking as it happens, and clean it up later. The result is an architecture decision record that actually reflects how the decision was made, not a sanitized post-hoc explanation.

Practical Setup for Developers

A few things that make voice dictation more useful in a dev environment:

Use a decent microphone. The built-in mic on a MacBook works, but a USB condenser microphone in the $50 to $100 range reduces transcription errors noticeably, especially if you're in a noisy environment.

Keep dictation scoped to prose contexts. Assign a keyboard shortcut you can hit quickly, speak your text, and move on. The lower the friction, the more often you'll actually use it.

Don't aim for perfect dictated prose. Speak naturally, then do a quick editing pass before committing the comment or doc. The goal is getting the information out of your head, not producing finished writing on the first pass.

Good documentation doesn't require more discipline. It requires less friction. If speaking a comment takes less effort than typing it, you'll write more of them. That's worth experimenting with.