How to Dictate Code Comments That Don't Sound Like a Robot Wrote Them

Most code comments are useless. They describe what the code does, which the code already describes. The comments worth reading explain why a decision was made, what edge case the function is guarding against, or what the previous approach was and why it failed.

Writing that kind of comment takes thought. Typing it out, while already mentally exhausted from writing the surrounding code, often means the comment either does not get written or gets written badly. Dictating it changes the dynamic in a way that is worth understanding.

Why Typing Comments Produces Bad Comments

When you type a comment, you are operating in the same mode as when you wrote the code. You are inside the syntax, thinking in terms of variables and logic. The comment ends up sounding like that: terse, abbreviated, written for a reader who already understands everything you understand.

When you speak a comment, you naturally shift register. You talk the way you would explain something to a colleague who just walked over to your desk. The explanation becomes longer, looser, and almost always more useful.

This is not a small difference. A spoken explanation of a tricky regex might take 40 words. The typed comment might say "validates input." One of those is helpful six months later.

Setting Up a Voice-First Comment Workflow

The practical setup is simple. Write the code. When you reach the point where a comment belongs, press your dictation shortcut, switch into explanation mode, and speak.

With a tool like VoiceInk, this means pressing a hotkey, speaking in plain language, and having the text appear directly in your editor without switching apps or windows. The comment lands where your cursor already is.

The friction is low enough that it does not break the coding flow. It is closer to thinking out loud than it is to writing.

What to Actually Say

There are three questions worth answering in any non-obvious comment. Why does this code exist? What would go wrong if it were removed or changed carelessly? Is there something about the context that future readers would not know just from reading the file?

Try speaking the answers to those questions instead of describing the logic. For example, instead of typing "checks if user is authenticated," you might dictate: "This guard exists because the downstream API does not return a useful error when called without a valid token. We learned that the hard way in the staging incident in March. If you remove this, expect silent failures."

That comment takes ten seconds to say. It would take most developers longer to type, and the typed version would probably be shorter and less useful.

Documentation Is the Same Problem at Larger Scale

Everything true about comments is also true about documentation. READMEs, internal wikis, architecture decision records, and onboarding guides all suffer from the same problem: the people who should write them are the people least willing to sit and type them after an already long day of coding.

Dictating documentation into a scratch file at the end of a task, while the context is still fresh, takes a few minutes. Cleaning up the transcript takes a few more. The result is documentation that exists, which is better than perfect documentation that was never written.

A Note on Technical Terminology

Speech recognition handles plain language well. Technical terms are more variable. Library names, function signatures, and product-specific jargon will sometimes require manual correction.

The practical fix is to dictate the explanation in plain language and type the technical tokens. "This function calls" spoken, then type the method name, then continue dictating. After a few sessions, you develop a natural rhythm for switching between the two.

Start With One Type of Comment

Pick the category of comment you write most reluctantly, probably the ones explaining architectural decisions, and try dictating those for a week. Notice whether the explanations are more complete. Notice whether you actually write them instead of leaving a placeholder that never gets filled in.

Voice is not a replacement for careful thinking. It is a lower-friction path for getting careful thinking out of your head and into the codebase where it belongs.