Warning: a senior dev told me my code comments were too basic and it changed how I write

I used to write comments like "this loops through the list" for every single function. My team lead pulled me aside after a code review and said "your comments explain what the code does, not why it exists." Now I focus on explaining the logic behind decisions instead of restating obvious stuff. Anyone else get feedback that totally shifted their approach?

2 comments

2 Comments

grant_palmer21d ago

Start writing your comments like you're explaining the code to a coworker who already knows how to code. Instead of "this method sorts the array," say "this sort puts finished orders first so the packing team sees them right away." Your lead was right - the "why" is what actually helps someone six months from now when they're trying to figure out if they can change that loop without breaking everything.

sanchez.mia21d ago

Does anyone else feel like they've been writing comments wrong for years? I know I've definitely been guilty of the "this method does x" style of comments. The "why" thing really hit home for me. I spent an hour last week trying to figure out why a coworker had put a timeout in a loop, and it turned out it was because the API they were calling would rate-limit us if we didn't wait. A simple comment like "waiting here so we don't get blocked by the API" would have saved me a lot of time.