A Few Things I've Learned About Writing Code Comments

"Clean code should ideally speak for itself..." they say, but let's be honest, it rarely tells the whole story. Good comments don't just explain what the code is doing; they tell you why. They're a conversation with your future self and your teammates.

Here are a few things I've learned over the years.

First, Write "Clean Code"

I have to start here, because it's the foundation. The best codebases I've ever worked in had surprisingly few comments. Not because the developers were lazy, but because the code was so clear you didn't need them as much (nothing is perfect).

Good naming, simple functions, and a logical structure go a long way. If you find yourself needing to explain every single line, it might be a sign that the code itself could be simpler.

Trying to decipher functions full of variables like x, y, and data is not fun, and if you find a bunch of comments explaining what those variables are, perhaps it's time to rename them.

ts
// I've seen this...
let x = 42; // Maximum number of retries
 
// When this is all you need
let maxRetries = 42;

Explain the “Why” Not the “What”

This is the biggest lesson I've learned. Some developers often write comments that describe what the code is doing. Other developers explain why it's doing it which I think is far more valuable. The "what" is usually obvious from the code itself, but the "why" is where the real value is.

Why did we choose this approach? Is there a weird business rule we have to account for? Was there a performance trade off we had to make? That's the context that saves your teammates (and future you) hours of head scratching.

ts
// This doesn't help much
let discount = price * 0.9; // Apply 10% discount
 
// This is what I want to know
let discount = price * 0.9; // Promotional discount for Black Friday

Don't Let Your Comments Lie

An outdated comment is worse than no comment at all. It's a landmine waiting to trip someone up. I've been there, you follow a comment, assume it's true, and end up debugging the wrong thing for an hour (no lie).

It's simple: if you change the code, change the comment. It's a discipline, but it's one of the most respectful things you can do for your team.

A Few Other Hard-Won Lessons

Over time, you start to notice the small things that make a big difference.

• Avoid the Obvious: A comment like // Add a and b for let total = a + b; just adds noise. Trust your reader to understand basic code.
• Be Consistent: It doesn't matter if you use // or /* */, just pick a style and stick with it. It makes the code feel clean and professional.
• Document Public Stuff: If you're writing an API or a function that others will use, give them the courtesy of a good explanation. A clear JSDoc block can save someone a lot of time.
• Spell It Out: I once saw a comment that said // TODO: Impl. caching. What does "Impl." mean? Implement? Implicate? It's a tiny thing, but clarity is kindness. Just write "Implement."

A Quick Word on "TODO"s

I have a love/hate relationship with TODO comments. They are great for flagging something you need to come back to, but they can also become a graveyard of good intentions.

I've found it's better to be specific. Instead of just // TODO: Fix this, I'll write // TODO(adrian): Optimize this function, it's slow with large datasets.. Even better, I'll just open a ticket for it. That way, it doesn't get lost in the codebase.

Final Thoughts

At the end of the day, writing good comments is about empathy. It's about thinking of the next person who will read your code whether it is a teammate or you in six months. It's not about rules, it's about being a good communicator.

And that's a skill that's just as valuable as writing the code itself. Remember, code comments are not a sign of bad code, they are a sign of thoughtful code.