On comments - Blog

On comments

2026-08-07

For the past decade or so, my syntax highlighting configuration has had an odd quirk in it:<br>code comments are bright orange, not the standard faded grey.<br>This wasn't an accident.<br>I wanted to force myself to get better at documenting code,<br>and what better way to do so than to make comments extremely in-your-face<br>so that any extraneous noise becomes painfully visible.

It's very easy to write useless comments in code;<br>comments that convey little beyond what can already be surmised from the nearby code,<br>that state obvious facts,<br>or that only make sense to the person who wrote them at the time that they wrote them.<br>Such comments stick out like a sore thumb when reading through code<br>(especially with my configuration).<br>They read like noise, polluting the flow of the code with irrelevant information<br>that causes the brain to lose its thread in the code.<br>This is especially apparent when comments reflect some previous iteration of the code,<br>but is no longer accurate,<br>and thus causes the reader to do a double-take and start doubting their own understanding.

And yet, comments can be hugely valuable when used well.<br>When a comment points out why the "obvious" restructuring of a bit of code won't work,<br>explains why a particular configuration option needs to be set in a library,<br>or highlights a corner case that the code doesn't support (and why),<br>it can save the reader hours or days of work and frustration.<br>And remember, that reader could be yourself 12 months from now<br>when you've forgotten all the details about how the code in question works!

Often, you won't even realize how much time and effort a single comment might have saved you,<br>as you just read it and move on.<br>It only becomes apparent if you consider what you would have done<br>if you had read the code without the comment,<br>spotted something weird-looking,<br>and decided to see if you could make it better.

I'm specifically talking about code comments,<br>not in-code documentation (eg, /// in Rust).<br>Documentation is written for your consumers.<br>Comments are written for your collaborators.<br>And while some of these lessons apply for the former,<br>I only want to talk about the latter (for today at least).

Just write more readable code!

It's no wonder that many engineers have a complicated relationship with comments.<br>We love them when they're good, hate them when they're noise,<br>and (perhaps subconsciously) worry about writing too many of them<br>in case they're just noise to others.<br>My experience has been that some engineers write fewer and fewer comments as they become more senior,<br>preferring instead to make their code easier to read by breaking up code,<br>using more descriptive function and variable names,<br>leveraging the type system more extensively, etc.

Those techniques are all worthwhile and good practice,<br>and they do result in code that's easier to read and understand.<br>But they do not replace comments.<br>Not fully.<br>Improving the readability of the code will, in general, make the "how" clearer, but not the "why".<br>Some limited comment-like code constructs exist,<br>such as Option::expect and unreachable! in Rust,<br>where you can pass in a string explaining why something is definitely Some or unreachable!,<br>but they primarily document invariant assumptions and not much else.<br>Information that was never written down cannot be recovered by reading harder.

What kinds of comments are useful?

There are a number of types of comments that in my experience are nearly always worthwhile.

The main ones are:

TODOs

You know the code isn't complete, finished, or fully polished,<br>but you also know it's not important that it isn't.<br>So, you leave a note to a future developer about what is outstanding and ship the thing.<br>Risky, perhaps, but the reality of software is that there are a lot of corner cases,<br>and we can often know that some simply aren't important at the moment<br>(ranging from "this could be optimized"<br>to "this corner case is complicated to implement but also highly unlikely to be relevant").

The main thing to remember with TODOs is to actually leave enough information<br>for the reader to understand what you meant.<br>When everything is fresh in our minds, it's easy to just jot down a few keywords,<br>but when the junior engineer is looking at it in six months time and you've left the team,<br>that TODO is probably going to remain just that — a to-do.<br>Multi-line TODOs are totally fine, as are outlines / partial steps for how to resolve,<br>and chances are the person who comes after you (or you yourself!)<br>will be happy you took the time.

Examples:

haphazard — src/domain.rs

noria — server/src/controller/migrate/routing.rs

noria — server/src/controller/migrate/assignment.rs

haphazard — src/lib.rs

Linking a TODO to a ticket can also be a good idea to have a space for discussion and tracking<br>while still keeping the strong connection to the code.

I'm personally not too fussed about the exact format of TODOs.<br>They need to contain the letters TODO (in that...