Rant: That senior dev told me my code comments were holding me back, and he was right

I used to write long comments explaining every line of JavaScript in our project. My senior dev pulled me aside after a code review and said your comments are making the code harder to read, not easier. He told me to write code that explains itself and only comment on the why not the what. I cut my comments down by 80% and now my pull requests get approved way faster. Has anyone else had to unlearn a habit they thought was a strength?

2 comments

2 Comments

lily_stone768d ago

@dakota160 that "why not the what" thing really stuck with me too. At first I was explaining every little thing like I was teaching someone who had never seen code before, but really I was just writing down my own thought process in real time. I mean, the code already says what it does right there in the syntax, so adding "this loops through the array" next to a for loop is just pointless noise. Once I started asking myself "what context about the business logic or the reason behind this decision would someone need to know," my comments actually became useful and my reviews got way less painful.

dakota1608d ago

That bit about "only comment on the why not the what" really hit me. Were your comments mostly explaining what the code does, or were you talking through your own thought process as you wrote it?