Dictating Code Comments: A Developer's Honest Take

Every developer knows they should write better comments. Most developers also know they do not. The reason is not laziness. It is that stopping to type out a clear explanation of what a function does, why it does it that way, and what the edge cases are, takes long enough that it breaks the flow of actual coding.

Voice dictation does not make you a better writer. But it makes the writing fast enough that you stop skipping it.

Where Voice Fits in a Coding Workflow

The sweet spot is not the code itself. Dictating variable names, function calls, and syntax is slow and error-prone. Your brain codes differently than it speaks, and fighting that is not worth it.

The sweet spot is everything around the code: comments, docstrings, README sections, commit messages, ticket descriptions, architecture notes, and internal documentation. These are prose, and prose is exactly where dictation earns its keep.

A developer who can speak clearly can produce a solid function comment in 15 seconds. Typing that same comment, with all the stopping and starting and second-guessing, might take 90 seconds. When you are commenting ten functions in a sitting, that difference is real.

Commit Messages That Actually Say Something

Commit messages are a particular failure mode in most codebases. They say things like "fix bug" or "update styles" because writing a real message feels disproportionate to the act of committing. Speaking changes that calculation.

When you can open a terminal, dictate a two-sentence commit message with actual context, and keep going, the barrier drops enough that you write the message you would have wanted to find six months later. That is worth something.

Capturing Decisions in the Moment

Some of the most valuable documentation is the kind that explains why a decision was made, not just what the decision was. Why did you choose this data structure? Why does this edge case get handled this way? Why is this timeout value 30 seconds and not 10?

This context lives in your head at the moment you write the code. An hour later it starts to fade. A week later it is mostly gone. If capturing it requires opening a separate doc and typing out a paragraph, it does not get captured. If it requires pressing a key and speaking for 20 seconds while you still have the thought, it does.

VoiceInk works in any app on your Mac, which means you can dictate into a comment block in your editor, a Notion page, a GitHub issue, or a Slack message without switching tools or modes. That frictionlessness is what makes the habit stick.

What About Accuracy With Technical Terms

Modern speech recognition handles common technical vocabulary better than most developers expect. Words like "boolean", "asynchronous", "middleware", and "refactor" come through cleanly. Where it stumbles is proper nouns, internal project names, and obscure library names.

The practical approach: dictate the prose, type the specifics. Speak the explanation, type the class name you are referencing. This hybrid works well once you find the rhythm, usually within a day or two of trying it.

The Documentation Debt Problem

Most teams have documentation debt, things that should have been written down but were not because writing felt too expensive in the moment. Voice dictation does not eliminate that problem, but it changes the cost calculation enough that the debt accumulates more slowly.

If speaking a paragraph takes 20 seconds and typing it takes two minutes, the rational choice changes. You write the paragraph. You explain the function. You leave the note that your future self and your teammates actually need.

If your documentation habits are worse than you want them to be, the problem might not be discipline. It might be friction. Try speaking your next ten comments and see if the habit gets easier.