Had an interview feedback session that completely changed how I structure my code comments

A senior dev told me last month that my comments were essentially just rephrasing the code in English. He said if your comment says 'adds 5 to the total' and the line is 'total += 5', you're wasting space. He told me comments should explain WHY you're doing something weird, not what you're doing. So I went back and deleted about 60% of my comments from my last project. Now I only write them when I'm doing something that looks wrong but isn't. Has anyone else had that moment where someone pointed out a bad habit you didn't even know you had?

2 comments

2 Comments

the_avery3d agoMost Upvoted

Heard a talk from this guy on a coding podcast a while back who compared bad comments to putting a label on a light switch that says "turns light on." Like yeah, we know what the switch does, that's literally its whole purpose. He said the best comments are basically apologies or warnings - "sorry this looks messy but here's why" or "warning: this function will delete everything if you pass True accidentally." That idea of comments being apologies really stuck with me, now I catch myself writing stuff like "this date math looks wrong but trust me it handles daylight saving time correctly.

carter.hugo3d ago

Oh man I totally used to be on the other side of this lol. I thought I was being helpful by writing comments like "this loop iterates through the user list" right above a standard for loop. It felt like I was documenting everything properly. But yeah a senior dev at my last job basically said the same thing to me and it clicked. Now I mostly just leave comments for the weird stuff like "this looks like a bug but actually the API returns negative numbers when it fails, so we handle it here." It saves so much time not having to read comments that just spell out what the code already says.