Dictating Code Comments: A Developer's Honest Take

Ask most developers why their codebase has sparse comments and the answer is always some version of the same thing: it breaks the flow. You're in the middle of a function, you know exactly what it does, and stopping to write three sentences of explanation feels like pulling your hands off a moving train. So you don't. And six months later, nobody remembers what that function does, including you.

Voice dictation doesn't fix the motivation problem. But it removes the friction problem, which turns out to be most of the problem.

Where Documentation Actually Falls Apart

The issue isn't that developers don't know what to write. It's that writing it takes long enough to feel expensive. Typing a clear docstring for a non-obvious function might take 90 seconds. That's not a lot, but spread across a session, it adds up, and more importantly, it breaks context. You leave the code to explain the code, and getting back takes another 30 seconds.

Voice collapses that cost. You look at the function, say what it does, and the comment is there. You never moved your hands from the keyboard. The context break is closer to zero.

What Works Well for Voice

Inline comments are the obvious win. Anything that's one or two sentences, a note about why you chose this approach over the obvious one, a warning about an edge case, a TODO with actual context, these are fast to say and tedious to type.

Docstrings are also strong candidates. The structure is predictable: what does this do, what are the parameters, what does it return. You can speak that structure naturally in about 20 seconds for most functions. Typing the same content, especially with formatting, takes longer and feels like form-filling.

README sections, architecture notes, and ticket comments are where dictation really stretches out. These are longer, more explanatory, and the kind of writing that developers put off the longest. Speaking them out in a conversational tone, then cleaning up the text afterward, is almost always faster than composing them by keyboard.

Setting Up a Workflow That Doesn't Interrupt You

The key is keeping dictation accessible without making it a mode switch. With VoiceInk, you press a configurable hotkey, speak, and the text appears in whatever app has focus, your editor, your ticket tracker, your Slack thread. You don't leave your flow. You stay in the file, look at the code, describe what you're looking at, and keep moving.

For code specifically, it helps to speak punctuation explicitly at first. Say "open paren", "colon", "new line" until you develop a pattern. Most developers find a rhythm within a few sessions. After that, it starts to feel like a natural extension of thinking through the code.

What Voice Won't Replace

Variable names, method calls, syntax, none of that should go through voice dictation. Voice is for natural language, and code is not natural language. The workflow that works is: write the code by hand, then immediately dictate the explanation without switching windows or losing your place.

That pairing is where the productivity gains actually live. You document while the reasoning is still active in your head, in the time it takes to say a few sentences, and you move on.

The Real Reason to Try It

The best argument for dictating documentation isn't speed. It's quality. When you speak an explanation, you tend to write the way you'd explain it to a colleague. Conversational, direct, covering the non-obvious parts. That's better documentation than most developers produce when they're forcing themselves to type through reluctance.

If your codebase has functions with no comments because commenting always felt like stopping, try saying the explanation out loud the next time you finish a function. It takes about fifteen seconds, and future-you will notice the difference.