Just realized I was commenting code like an idiot for 6 months

I used to write stuff like 'this adds the numbers' right next to a line that literally says 'x + y'. Thought I was being thorough. Then a senior dev in my online bootcamp straight up told me my comments were useless and actually made the code harder to read. He showed me a fix where I explained the why, not the what, like 'handles edge case when user enters zero'. That one tip saved me so much time debugging last week. Has anyone else had their code comments ripped apart and learned something from it?

3 comments

3 Comments

wilson.olivia14d ago

Nah I gotta push back on this. Comments explaining "why" can be just as useless if you're not careful. I've seen code where people write stuff like "fixes performance issue" and then the actual "fix" is a total hack that breaks three other things. The why comment becomes a lie six months later when nobody remembers the original context. Concrete examples matter, sure, but the real problem is people thinking any comment is better than none. Half the time you're better off just writing cleaner code that explains itself. Like that "handles edge case" example - what does that even tell you? Either the code handles it or it doesn't. The comment just states the obvious.

felixlane14d ago

That "explain the why not the what" tip is the exact kind of stuff they don't teach in tutorials. But here's my question: did that senior dev give you any specific examples of bad comments he'd seen in YOUR code, or did he just give a general rule? I always find concrete examples way more useful than abstract advice. Like when he showed you 'handles edge case when user enters zero' was that from something you actually wrote or just a random example he made up on the spot?

charles83614d ago

Man that senior dev just gave me a random example, probably because he looked at my code and realized the problem was way bigger than one comment could fix... like my entire file was a museum of useless comments. I had one that literally said "this loops through the array" and I thought I was being helpful until he pointed out the loop was right there in plain sight. Worst part is he didn't even yell at me, just gave this sad little sigh that made me feel like I'd let down the whole profession.