Kilroy Was Here

When I see a comment explaining a piece of code, a little voice in my head often says something like:

“I didn’t have time—or I was too lazy—to write this clearly, so I’ll just drop a quick comment and call it a day.”

But that’s a trap. Not all comments are signs of laziness.

In fact, good comments can be a sign of respect.

When my wife and I don’t cross paths in the evening, I sometimes leave her dinner ready and a short note where she’ll see it. That way, she knows there's something in the fridge, she doesn't waste time wondering what to make, and she can go straight to the microwave. I usually add a kind phrase too—because why not.

I'm not saying you should express your love to other developers in your code (at least not explicitly), but you should be kind enough to leave the kind of comments that actually help. Because yes, code should ideally explain itself. And yes, git history is there. And sure, a senior developer will often figure it out quickly. But real life is too short to play detective every time. And sometimes, you just don’t have the time.

Here are a few examples of comments that make a real difference:

• // Important: must happen after userService.save(), otherwise email won’t include user ID
• // This workaround is due to a known issue in libX v2.3. Remove after upgrade to v2.4
• // We use polling here instead of websockets because of client firewall restrictions
• // Keep this ordering! The migration script depends on it.

When you leave a comment, ask yourself: Will this save someone a few minutes of confusion later? Will it help them understand not just what’s happening, but why it’s done this way?

If so, it’s worth writing.

exit(0);