← Back to Blog

Short answer: To dictate code comments, place your cursor on the comment line, trigger your voice tool, and speak the explanation in plain English. Voice Keyboard Pro types it at your cursor in any editor, so you describe the "why" at speaking speed and keep syntax on the keyboard.

Most developers know they should comment their code better. They also know they rarely do. The reason is almost never laziness. It is friction. You are in flow, holding a fragment of logic in your head, and the moment you stop to write a sentence of prose explaining it, you context-switch from thinking in code to composing in English. By the time you have typed three lines of explanation, the thread you were holding is gone. So the comment gets skipped, shortened to something useless like // fix later, or never written at all.

Voice changes that calculation. You already think in sentences. When you explain a tricky function out loud to a colleague, the explanation comes out clean, ordered, and complete because speaking is the format your brain uses for reasoning. Dictation lets you capture that explanation directly into the file without the typing tax. This guide covers how to dictate code comments and documentation on a Mac, what to speak versus what to keep on the keyboard, and the small habits that make voice comments accurate the first time.

Why Comments Get Neglected

There are three structural reasons good comments are rare, and all three are about cost rather than intent.

The prose-versus-code switch. Writing code and writing English use different mental modes. Comments force you to flip between them mid-task, and each flip has a cost. The more comments you try to write, the more flips you pay for.

Typing speed caps how much you will write. A strong developer types at 80 to 100 words per minute on good days, slower when the comment requires careful wording. People speak at 130 to 150 words per minute without effort. When explaining something is slow, you explain less. When it is fast, you explain more, and you explain the part that actually matters.

Comments document the "why," and "why" is the hardest thing to type concisely. Good comments do not restate what the code does. They capture intent, constraints, the bug that made this line necessary, the edge case that is not obvious. That is exactly the kind of nuanced, sentence-shaped reasoning that flows naturally when spoken and feels like a chore when typed.

Remove the typing cost and the math flips. Suddenly a two-sentence explanation of why a retry has a five-second backoff costs you nothing, so you write it. The next engineer to touch that code, possibly you in six months, gets the context for free.

The Setup: Dictating Into Any Editor on Mac

Voice Keyboard Pro is a native macOS menu bar app that types wherever your cursor is. It does not care whether the cursor is in VS Code, a JetBrains IDE, Xcode, a terminal, Vim in a terminal, or a GitHub pull request in your browser. The flow is the same everywhere:

  1. Put your cursor where the comment should go and open the comment syntax yourself (//, #, /*, or a docstring opener) with the keyboard.
  2. Hold your dictation hotkey.
  3. Speak the explanation as if you were telling a teammate what this code does and why.
  4. Release. The text lands at your cursor in under a second.
  5. Glance, fix any term that came out wrong, move on.

Because it works system-wide, you are not locked into a single editor's built-in dictation or a plugin that only exists for one IDE. The same hotkey writes comments in your Rust project, your Python notebook, your Bash script, and the design doc you have open in another tab. If you already lean on voice for other parts of your day, this is the same muscle memory described in our guide to dictation for coding.

Speak the Prose, Type the Syntax

The single most important principle for dictating code comments is knowing where the boundary sits. Voice is excellent for natural language and clumsy for punctuation-dense symbols. So draw a clear line:

In practice this means you open the comment block with the keyboard, dictate the human-readable part, and then go back with the keyboard to wrap any variable names in backticks or fix capitalization. Trying to speak every brace and colon is the mistake that makes people give up on voice. You would not dictate the code itself this way, and comments are no different: let your voice do what it is good at and let your fingers handle the symbols.

The goal is not hands-free coding. The goal is to make the explanation cost nothing so you actually write it.

Dictating Each Type of Comment

Inline and block comments

These are the everyday comments that explain a line or a section. Open the marker, then speak one or two sentences. Aim for the "why," not the "what." Instead of dictating "loop over the users," which the code already shows, dictate something like "We process users in batches of fifty because the downstream API rate-limits anything larger." That sentence is effortless to say and genuinely useful to read, and it is exactly the kind of thing nobody types because typing it is annoying.

Docblocks, docstrings, and JSDoc

Structured documentation comments such as Python docstrings, JSDoc, or Javadoc have a fixed skeleton of tags and a free-text description. Type the skeleton, dictate the descriptions. Open the docstring, type @param userId, then dictate "the unique identifier of the account being charged." Type @returns, then dictate "a promise that resolves once the receipt has been emailed." The tags are muscle memory on the keyboard; the descriptions are where voice saves you real time and where most developers write something lazy or nothing at all.

TODOs, FIXMEs, and notes to your future self

This is where voice quietly shines, because the comments you leave for future-you are the ones you most often truncate. A typed TODO becomes // TODO refactor. A spoken one becomes "TODO: this works but allocates a new buffer on every call, which showed up in the profiler under load. Pool it before we ship to production." The spoken version takes the same five seconds and carries ten times the information. Type the TODO: tag, dictate the context.

Commit messages and PR descriptions

The documentation that matters most is often the documentation around the code rather than in it. Commit messages and pull request descriptions explain intent across time, and they are notoriously thin because typing a paragraph after you have finished the actual work feels like overhead. Dictating them removes that overhead entirely. Speak a real summary of what changed and why, speak the testing notes, speak the rollback plan. Because the cost dropped to near zero, the quality goes up. Many developers find this is where voice pays for itself fastest, alongside the other patterns in our roundup of five ways developers use voice to text daily.

Keeping Technical Vocabulary Accurate

The fair objection to voice in a technical context is vocabulary. General transcription expects everyday words, and your codebase is full of product names, framework names, and invented identifiers that no general model has ever seen. Spoken aloud, "Kubernetes," "nginx," "OAuth," or your internal service name "Pegasus" can come back mangled.

Voice Keyboard Pro handles this with Smart Vocabulary, a personal dictionary with replacement rules. You add the terms you say constantly, including the way you pronounce them, and the app renders them correctly every time. If you always say "kube cuddle" for kubectl, you teach it that mapping once and it stops fighting you. This is the difference between voice being a novelty and voice being a tool you keep using: after a week of adding the dozen terms specific to your stack, accuracy on your own jargon stops being a problem. Set this up early rather than abandoning dictation over a few mis-transcribed names.

One thing worth being clear about: Voice Keyboard Pro's transcription engine processes your audio and returns text, and the company stores only operational pings, never your audio or the content of what you dictate. Your comments, your code references, and your internal service names are not retained on any server.

Scaling Up to Full Documentation

Once dictating comments feels natural, the same workflow extends to documentation that lives outside the code: READMEs, architecture notes, API references, and onboarding guides. These long-form documents are where the speed gap compounds most, because they are mostly prose with occasional code blocks.

The technique is to dictate the explanation first and structure it second. Open your README, put the cursor under a heading, and talk through the section as if you were onboarding a new hire: what this service does, what it depends on, how to run it locally, what breaks first. Get the full thought down at speaking speed, then go back with the keyboard to add headings, fenced code blocks, and links. Drafting by voice and editing by hand is dramatically faster than typing carefully composed prose from a blank page. If your work involves a lot of this, our deeper guide to dictation for project documentation walks through a full documentation-first workflow.

A realistic example

Say you just finished a tricky caching layer. The old workflow: you mean to document it, you are tired, you type a one-line README entry and move on. The voice workflow: you put the cursor in the README, hold the hotkey, and spend ninety seconds saying out loud exactly what you would tell a teammate. "The cache uses a two-tier design. Hot keys live in memory with a sixty-second TTL, and everything else falls through to the shared store. We invalidate on write rather than on a timer because stale pricing data caused a support incident last quarter." Release, fix the two product names that came out wrong, add a code fence around the config snippet. Two minutes, and the next person to touch this code understands the design decision and the incident that drove it.

Common Pitfalls and How to Avoid Them

Trying to dictate the code itself. Voice is for the prose around the code. Symbol-heavy source is faster on the keyboard, and the fastest developers, as we cover in fast typing for coding, keep their hands on the keys for the actual logic and reach for voice on the human-language parts.

Speaking punctuation you do not need. For most comments you can speak naturally and add the final period yourself, or say "period" only where it matters. Over-narrating every comma slows you down and rarely improves the result.

Skipping the vocabulary setup. The developers who quit voice usually quit in the first hour over a mis-transcribed framework name. Five minutes in Smart Vocabulary prevents that.

Editing while you dictate. Get the whole thought out, then fix it. Stopping every few words to correct a term breaks the flow that makes voice fast in the first place.

The Bottom Line

Comments and documentation are not skipped because developers do not value them. They are skipped because the cost of writing them, in flow disruption and typing time, is higher than the immediate payoff. Dictation removes most of that cost. You explain the "why" at the speed you think, keep the syntax on the keyboard where it belongs, and end up with code that the next engineer can actually read.

Voice Keyboard Pro is a native macOS menu bar app that types wherever your cursor is, with Smart Vocabulary for the terms only your codebase knows. There is a free tier with daily limits, and Pro is $4.99 a month or $34.99 a year. Hold the hotkey, explain your code the way you would to a colleague, and let the comment write itself. The next time you read your own code six months from now, you will be glad the explanation is there.

Keep reading