Dictating Code Comments: A Developer's Field Guide

Nobody writes enough comments. This is not a hot take. Every developer knows it, every codebase shows it, and the reason is the same every time: it is slow and it feels like interrupting yourself.

You just solved a tricky problem. Your brain is still warm with context. The last thing you want to do is stop and carefully type out an explanation of what you just did. So you write a one-liner that will mean nothing in six months and move on.

Dictating changes this. Talking is how you already explain code to other people.

Why Dictation Fits Documentation Better Than Typing

When a colleague asks you how a function works, you do not compose sentences in your head first. You just explain it. That explanation is usually better than anything you would type, because speaking pulls from a different part of how you understand the problem.

Typed comments tend to be terse and noun-heavy. Dictated comments tend to include the why, the edge case you were thinking about, the tradeoff you made. The extra context that makes a comment actually useful.

VoiceInk runs locally on Mac and puts your words wherever your cursor is. For documentation, that means you can position your cursor in a comment block and talk through the logic without switching windows or tools. The transcription is fast enough that you can dictate and read back before you lose the mental context.

What to Dictate and What to Type

Not everything benefits from being spoken. A few patterns that work well for dictation:

Function and method docstrings. Position your cursor, take a breath, describe what the function does, what it takes, what it returns, and any side effects. Do this right after writing the function while the reasoning is fresh.

Inline comments on non-obvious logic. Regex patterns, bit manipulation, performance-specific choices. Say out loud why it is written that way instead of the obvious way.

README sections and architecture notes. These are basically prose anyway. Dictating them produces a more readable document than typing usually does.

TODO and FIXME annotations. Describing the problem takes four seconds to say and often thirty seconds to type carefully enough to be useful later.

Leave variable names, function signatures, and anything requiring precise syntax to your keyboard. Dictation is for human-readable text.

A Simple Workflow

Finish a function or a logical block. Before moving to the next task, pause and dictate a comment. Do not aim for perfect prose. Aim for the explanation you would give to a new team member looking at this code six months from now.

This takes roughly fifteen to thirty seconds. It produces documentation that is actually read, because it sounds like a person wrote it with something to say rather than a developer fulfilling a documentation requirement.

Over a week, the habit compounds. Your codebase becomes easier to navigate, onboarding new contributors gets faster, and your own future self stops cursing your past decisions.

Reducing Physical Load During Long Sessions

Developers are high-volume keyboard users. Wrist and hand fatigue is a real occupational risk, and documentation is often what pushes you into overtime on a heavy coding day.

Moving non-code text out of your hands and into your voice is a meaningful reduction in keystroke load. Not because dictation replaces the work, but because it routes it through a different, less-fatigued channel.

If you already feel tension in your hands after a long sprint, consider reaching for your voice before adding another thousand keystrokes of documentation to the session.

The comments you skip today are the confusion you debug six months from now. Dictating them removes the main reason you skip them in the first place.