Got some unexpected feedback from a senior dev during code review

I was submitting my code for review and a senior developer pointed out that my comments were too vague. He suggested I be more detailed, but when I did, another reviewer said it was overkill. I mean, idk how to balance this stuff. Maybe it's just me, but has anyone figured out the right amount of documentation?

3 comments

3 Comments

lily39428d ago

Consider just leaving the code to speak for itself... honestly half the comments I see just state the obvious and clutter everything up. If someone can't figure out the code from reading it, maybe the real problem is the code itself being too messy. You can waste so much time writing comments that just get outdated in a week. I'd rather deal with a few vague notes than read a novel explaining every single line.

reese_ward5028d ago

My code is so clean it explains itself, said no one ever while debugging my spaghetti at 2 AM. Guess we found why my comments look like a desperate diary.

young.val26d ago

Ever notice how this same fight happens with instruction manuals or recipe blogs? People either want every tiny step written out or they get mad about too much fluff before the actual steps. It feels like we're all just guessing how much help the next person will need, and usually guessing wrong.