Dictating Code Comments: A Developer's Guide

Every developer knows they should write better comments. Most developers do not. The reason is not laziness. It is friction. Writing a clear comment takes almost as long as writing the code, and at the end of a focused session, switching to prose feels like a gear shift nobody wants to make.

Dictation removes most of that friction.

The Documentation Problem Is a Speed Problem

When you are deep in a function, you understand exactly what it does and why. That understanding is worth capturing. But typing it out breaks the flow, costs time, and gets skipped.

Speaking a comment takes 10 to 15 seconds. You look at the function, press a key, say what it does, and move on. The comment exists. The context is not lost. The future version of you, or your teammate, finds a sentence that explains the intent instead of having to reverse-engineer it.

What to Dictate as a Developer

Code comments are the obvious starting point, but they are not the only use case. Consider:

Inline comments. Dictate the why, not the what. "This workaround handles a race condition in the Safari WebSocket implementation" takes 5 seconds to say and would have saved someone three hours of debugging.

Function and method documentation. Before you write a function, dictate a one-sentence description of what it should do. After you write it, dictate what it actually does. The difference between those two sentences is often useful.

Bug notes and TODOs. When you notice something wrong but do not have time to fix it, dictate a note. Speaking a TODO is faster than typing one, which means you actually leave the note instead of thinking you will remember it later.

Stand-up and Slack updates. Dictating your daily update into Slack or a notes app takes 30 seconds. Typing the same update while you are already tired of typing takes longer and often gets abbreviated past the point of usefulness.

Setting It Up

VoiceInk works directly in your code editor. In VS Code, Xcode, Zed, or wherever you work, you press the dictation key, speak, and the text appears at your cursor. No plugin required. No special mode.

For comment syntax, the fastest approach is to type the comment delimiter yourself and then dictate the content. Type // or # or /**, then trigger dictation. Your fingers handle the character, your voice handles the words.

Managing Accuracy

Dictation accuracy is high for plain language. It is less reliable for technical terms, variable names, and library names you use in comments. Two adjustments help:

First, avoid dictating exact code names into comments. Instead of saying "the getUserFromCache function," say "this function." Comments are for humans, not compilers, so natural language works fine.

Second, do a single read-through after dictating any block of text. You are looking for mishearings, not rewriting. It takes 10 seconds.

The Actual Benefit

The real payoff is not speed per session. It is that you actually write the documentation instead of skipping it. A 60 percent accurate comment that exists is more valuable than a perfect comment that never gets written.

Developers who use voice for documentation consistently report that their codebases become more readable over time, not because they became more disciplined, but because the cost of leaving a comment dropped low enough that leaving one became the default.

If your codebase is sparsely documented, the problem is probably not attitude. It is friction. Try dictating your next ten comments and see if the math changes.