Dictating Code Comments: A Developer's Honest Take

Every developer knows they should write better comments. Almost every developer writes fewer than they intend to. The reason is not laziness. It is that stopping to type a block comment in the middle of a flow state feels like it costs too much. You are solving a problem. Switching to documentation mode breaks the solve.

Voice input does not fix this completely, but it changes the cost in useful ways.

Where Comments Actually Die

The comments that never get written are almost always the high-value ones. Not the obvious line-by-line narration that clutters bad codebases, but the why comments. Why this approach and not the obvious one. Why this edge case needs handling. What will break if someone changes this threshold.

Those comments require a complete thought, not just a label. And a complete thought, typed mid-problem, costs around 30 to 60 seconds plus the re-entry cost of getting back into the flow state. Experienced developers make an unconscious calculation and decide the comment can wait. It usually never comes.

Speaking a comment takes 8 to 15 seconds. That changes the calculation.

How to Actually Set This Up

The workflow is simpler than it sounds. Keep your cursor inside the comment block you want to fill. Trigger your dictation tool, speak the comment naturally, stop. On a Mac, VoiceInk handles this without leaving your editor. No extra window, no mode switch. The text appears where your cursor is.

The key is speaking the way you would explain the code to a colleague, not the way you would type a comment. Spoken explanations tend to be clearer than typed ones because you are not fighting the urge to be terse for typing efficiency.

What Works Well and What Does Not

Prose comments transcribe cleanly. Function-level documentation blocks, README sections, commit messages, architecture notes, internal wiki entries, all of these are good candidates for voice input. Anything that is primarily natural language benefits.

Code itself is a different story. Variable names, syntax, operators, these are awkward to dictate and easy to mistype by voice. Do not try to replace keyboard coding with voice coding. That is not what this is for. The goal is reducing the friction on the documentation layer, not the logic layer.

Technical terms are mostly fine. Modern transcription handles words like asynchronous, refactor, idempotent, and deprecate without drama. Acronyms sometimes need help, but you can speak them letter by letter when needed.

The Commit Message Problem

Commit messages are a small thing that compounds badly over a project's life. Most developers write minimal commit messages because typing them feels like overhead after the actual work is done. Lazy commits make code archaeology painful.

Dictating a commit message takes about the same time as reading the diff one more time. You can speak three sentences describing what changed, why it changed, and what to watch out for, in the time it normally takes to type a single terse line.

This is one of those small workflow changes that makes you look more professional and costs almost nothing once it becomes habit.

Documentation That Actually Gets Written

The documentation problem in software is not that developers cannot write. Most can write clearly when they try. The problem is that writing in the middle of a technical task carries enough friction that it gets deferred, and deferred documentation becomes no documentation.

Voice input does not make documentation exciting. It makes it cheap enough to do in the moment, which is the only moment it reliably gets done.

If you work on a Mac and spend time writing code, try dictating your next three block comments instead of typing them. Notice whether the result is more complete than what you would have typed. For most people, it is.