That time a senior dev told me to stop over-commenting my code

I used to comment every single line. Felt like I was being thorough. Then a guy named Dave on my team pulled me aside and said 'if your code needs this many comments, your code is the problem.' He was right. I started writing cleaner functions with better variable names instead. Cut my comments by 80% and the code reads way better now. Anyone else get told they were over-explaining?

2 comments

2 Comments

the_patricia2d ago

Read a thing from some coding blog that said comments should explain the 'why' not the 'what'. Completely changed how I think about it. Now I only comment when the logic is weird or there's a business reason that isn't obvious from the code itself. Saves a ton of time and makes my code actually cleaner.

garcia.miles2d ago

Thing is, keeping the "what" comments is actually fine in moderation when the code isn't obvious, like a weird regex or something. @the_patricia you're right about the why part being the important one, but it's not always a rule. I've seen people go too far the other way and then nobody can follow a simple loop without a one-liner reminder what it does lol.