Pro tip: stop using comments to explain what your code does, use them to explain why

I see beginners all the time writing comments like // this adds 1 to x right above x += 1. That tells me nothing I can't already see from the code itself. The real trick I figured out after about 6 months of coding is that comments are better for explaining the reasoning behind a decision. Like why you chose a loop over a built-in function, or why you're handling an edge case in a weird way. I caught myself doing it wrong when I went back to fix a script I wrote 3 weeks earlier and had zero clue why I set a variable to 0 instead of null. Now I write comments that sound like a note to my future self, not a textbook definition. Has anyone else had that moment where your own comments made you angry because they were useless?

3 comments

3 Comments

mary77611d ago

I get it, but I think people get a little too worked up over this. A comment that says // increment x by 1 above x += 1 is dumb, sure, but let's not act like it's ruining your life or your codebase. Some of my old scripts have zero comments and I still figure them out in 5 minutes, other times I spend an hour on something with perfect comments. It's just not that deep most of the time. I'd rather have a slightly useless comment than no comment in a tricky spot. Honestly, half the time my "why" comments are just me writing down a thought I had at 2am that still doesn't make sense the next day.

jennysullivan10d ago

How's that 2am habit working out for you?

piper_reed11d ago

Honest question though, is it really that deep? You're basically saying "a bad comment is better than no comment" but that's how you end up with a codebase full of junk that nobody trusts anymore. Seen plenty of projects where people slap // get user data above a getUser() call and suddenly nobody wants to remove it because "maybe it's important." It's not about ruining your life, it's about death by a thousand paper cuts. One silly comment is whatever, but a whole team doing that for six months? Now you've got a giant mess and everyone's scared to touch anything.