How to Dictate Code Comments That You Will Actually Keep

Most developers document in the past tense. Meaning they write the code, ship it, and intend to comment it later. Later never comes. The function sits undocumented until the next person, or future you, has to reverse-engineer it from scratch.

The problem is not laziness. It is friction. Stopping to type out a comment breaks flow. Voice dictation makes commenting fast enough that you will actually do it.

Why Documentation Gets Skipped

When you are deep in a problem, switching from writing code to writing prose is a context shift. Your hands are on the keyboard. Your brain is in the logic. Stopping to type a comment means leaving that state, composing a sentence, then trying to find your way back.

Speaking does not break that state in the same way. You can look at a function, say one sentence about what it does, and keep moving. The switch costs two seconds instead of twenty.

What to Dictate and When

The best time to dictate a comment is immediately after you write a piece of logic that took you more than five minutes to figure out. That is the moment you fully understand it and future readers will not.

Dictate the why, not the what. The code already shows what it does. Say why you made a specific decision, what the edge case is, what you tried first and abandoned. That is the information that disappears fastest and costs the most to reconstruct.

A few high-value targets for dictated comments:

• Any conditional with three or more branches
• Workarounds for third-party library bugs
• Functions with non-obvious side effects
• Performance-sensitive sections where a naive approach would be wrong
• TODO notes with actual context, not just "fix this"

Setting Up a Voice-First Documentation Habit

The habit works best when dictation requires no setup. Tools like VoiceInk let you press a shortcut in any app, speak, and have the text appear at your cursor. That means you can dictate directly into your IDE without switching windows or changing modes.

Try this workflow for one week. After finishing any function longer than fifteen lines, press your dictation shortcut and say one to three sentences above the function signature. Do not think too hard about it. Say what the function does, why it exists, and any edge cases worth knowing. Then move on.

You will not produce perfect documentation. You will produce documentation that exists, which is already better than most codebases manage.

Dictating Commit Messages and PR Descriptions

Commit messages are another place where voice dictation pays off fast. The average developer writes something like "fix bug" or "update styles" because typing a real description feels slow. Speaking one takes ten seconds.

PR descriptions are worse. Most are empty or copy-pasted from the ticket title. A spoken walkthrough of what changed and why, even just four sentences, saves reviewers real time and creates a record that survives the PR process.

Open the description field, press your dictation shortcut, and explain the PR the way you would to a colleague standing behind you. That is the description. You are done.

The Compounding Return

Good documentation pays off slowly and then all at once. The first week you dictate comments, nothing feels different. Six months later, you open a file you have not touched since and understand it immediately. The time you saved by skipping comments is never as large as the time you lose reconstructing them.

Voice dictation does not make documentation interesting. It makes it fast enough to stop avoiding. That is the whole argument.

If your codebase has files you are afraid to touch because nobody remembers how they work, try spending one session dictating comments through the worst offenders. See how long it actually takes.