Write Better Code Comments by Speaking Them

Bad code comments are worse than no comments at all.

You know the ones I mean:

// increment counter
counter++;

// get user
const user = getUser();

// TODO: fix later

These comments add noise without adding signal. They explain what the code does (obvious) rather than why it does it (useful).

I have a theory about why this happens: typing comments is tedious, so we minimize what we type. The result is comments that are terse to the point of uselessness.

Voice changes this completely.

The Voice Comment Difference

When you speak a comment instead of typing it, verbosity becomes natural rather than costly. You explain things like you would to a colleague.

Typed: // Check token expiry

Spoken: // We check for token expiry here because the OAuth provider sometimes sends tokens that are already expired, especially during daylight saving time transitions. See incident report from March 2024.

That spoken comment took about 10 seconds. Typing it would have taken 30+ seconds and felt excessive. So when typing, I wouldn't bother.

The "Future You" Test

Here's how I decide what to comment: I imagine opening this code six months from now, having completely forgotten I wrote it.

Then I speak out loud what I'd want to know. That becomes the comment.

"Why am I using setTimeout here instead of setInterval? Oh right, because setInterval can stack up if the callback takes longer than the interval, and this process is variable-time. That should be a comment."

Types of Comments That Benefit Most

Why Comments

Explaining why something is done a certain way. These are almost always valuable and almost always under-written.

// We use a Map instead of an object here because we need
// to preserve insertion order for the UI display. Object
// key order is technically guaranteed in ES2015+ but some
// transpilation targets don't honor it consistently.

Context Comments

Linking code to external factors: business requirements, technical constraints, historical incidents.

// Legal requires us to keep these logs for 7 years minimum.
// See compliance ticket LEGAL-2847 for the full requirements.

Warning Comments

Future-proofing against mistakes.

// WARNING: This function is called from the payment webhook.
// Any exception here will cause the payment to be retried,
// potentially resulting in duplicate charges. Handle all
// errors gracefully.

The Comment Speaking Flow

My process:

1. Write the code
2. Read it back to myself
3. At any point where I pause to remember what something does, speak a comment
4. Let transcription capture it
5. Light cleanup for formatting

This naturally creates comments at the exact points where future readers will also pause—because those are the confusing parts.

A Cultural Shift

The best engineering teams I've worked with have thorough, narrative comments. The worst have terse or missing comments.

It's not a coincidence. Good comments reflect a culture of knowledge sharing and long-term thinking. Voice commenting lowers the barrier to creating that culture.

Next time you're about to write // handle error, stop. Speak what you'd tell a colleague. Your future teammates will thank you.