Dictating Code Comments That Actually Get Written

Everyone knows code should be commented. Everyone also knows that at the end of a long session, writing documentation feels like the most expensive thing you could do with your remaining energy. So it does not get written. Three months later, nobody remembers why that function works the way it does, including the person who wrote it.

Voice dictation does not make you a better developer. But it removes the friction that stops good habits from forming.

Why Comments Get Skipped

The reason is not laziness. It is cost accounting. After an hour of intense focus building something, switching to write prose about it feels like a context shift that costs more than it returns. Typing a useful function comment takes maybe 90 seconds. That sounds trivial. But it rarely feels trivial when you are in the middle of a session.

Voice changes the calculation. Speaking a comment takes 10 to 15 seconds. You can do it without lifting your hands from the keyboard or meaningfully breaking focus. The cost drops low enough that the habit actually sticks.

How to Set This Up

The workflow is simple. Write your function. Before moving to the next one, press your dictation key, speak the comment in plain language, and keep going. You do not need to speak in perfect syntax. Most of the time, plain English is exactly what a good comment should contain.

With VoiceInk, your spoken words appear wherever your cursor is. That means you can speak directly into your editor, whether that is VS Code, Xcode, Neovim, or anything else. No special plugin. No integration to configure. Your cursor is in the comment block, you speak, and the words are there.

A comment that might take you 90 seconds to type takes 12 seconds to say. Over a four-hour session, that adds up to a meaningful difference in how often you actually write them.

Dictating Documentation and READMEs

Longer documentation is where dictation shows its real value for developers. READMEs, architecture notes, and PR descriptions are all prose-heavy work that most developers find tedious. They are not hard to write, they are just slow to type when your brain is already tired from solving actual problems.

Try this: after you finish a feature, open your README or your PR description and dictate it the way you would explain it to a teammate. Do not compose it in your head first. Just explain what you built, why you built it that way, and what someone needs to know to use it. Then clean it up.

The output is almost always clearer than documentation written by typing, because explaining something out loud naturally produces simpler language.

Capturing Decisions While You Still Know Why

One of the most valuable things a developer can document is not what code does, but why a decision was made. Why did you choose this library over that one? Why is this limit set to 100 and not 50? Why does this edge case get handled separately?

These decisions are obvious in the moment and invisible three months later. Dictating a quick note while the reasoning is fresh costs almost nothing. A 20-second voice note captured in a decision log or a comment block saves hours of archaeology later.

The habit only works if it is easy. It has to be faster than skipping it. Voice gets close to that threshold.

Start with One Session

Pick your next development session and set one rule: comment every function you write, using your voice. Do not slow down to type them. Just speak them as you go.

At the end of the session, read back what you captured. It will not be perfect. It will be better than nothing, which is what most codebases have. And it will have cost you almost no time.

If your documentation habit has always broken down at the point of actually writing, try seeing what changes when writing is just talking.