Dictating Code Comments: A Developer's Honest Take

Every developer knows they should write better documentation. Almost no developer does it consistently. The reason is not laziness. It is friction. After you have spent 45 minutes solving a problem, the last thing you want to do is switch modes and write prose about it.

Dictating that prose takes about 30 seconds. That changes the math.

The Part of Your Job Nobody Does Well

Code comments, function documentation, architecture notes, README files. These are the artifacts that make a codebase livable six months from now. They are also the things that disappear when a deadline appears.

The typing version of writing a good function comment looks like this: finish the function, context switch to writing mode, type out an explanation, second-guess the wording, edit it twice, lose the original thought halfway through. By the time you are done, five minutes have passed and the comment is mediocre anyway.

The dictation version looks like this: finish the function, press a key, say what the function does in one or two sentences, release the key. Done in under a minute, and the explanation usually sounds more natural because you are not forcing it through a keyboard.

Where Dictation Fits Into a Dev Workflow

The most useful places to add voice capture are not inside the code itself. They are around it.

Architecture notes work well as dictation. When you figure out why you structured something a certain way, that reasoning is freshest in your head right at that moment. Dictating a quick note into a project doc, a Notion page, or even a plain text file takes 45 seconds. Reconstructing that reasoning three months later takes 45 minutes.

PR descriptions are another strong use case. Most developers write minimal pull request descriptions because the cognitive cost of context-switching to write prose feels high. Dictating a description while the code is still fresh in your mind produces a better PR in less time.

Slack messages and internal updates also translate well. If you need to explain a technical decision to a non-technical teammate, speaking it out tends to produce clearer language than typing it under time pressure.

What About Accuracy with Technical Terms

This is the first question most developers ask. Technical vocabulary, variable names, and library names are where general dictation tools stumble.

VoiceInk runs on Whisper-based transcription locally on your Mac, and it handles common technical terms better than you might expect. It will not always get a specific library name right on the first pass, but for everything around the code, the explanations and the reasoning and the architecture notes, accuracy is high enough to use without heavy correction.

For the terms it misses, the fix takes two seconds. The time you saved on the rest of the paragraph still comes out ahead.

A Habit Worth Building

The developers who document well are not the ones with the most discipline. They are the ones who made documentation cheap enough to do without thinking about it.

If writing a code comment costs you 90 seconds of context-switching and typing, you will skip it when you are busy, which is most of the time. If it costs you 20 seconds of speaking, you will do it because the cost is low enough that skipping it feels wasteful.

Try it on a single PR this week. After you finish a piece of work, before you push, dictate the description and any inline comments that felt complicated to write. Note how long it takes and what the output quality is.

Documentation is the part of development that pays off the most in the long run. It just needs to be cheap enough to actually happen.