Can we talk about how I had comments in my code all wrong

I used to think writing a comment for every line made my code easier to follow. Then a senior dev at my first job looked at my Python script and said 'this is just noise, not help.' He showed me how comments should explain the why, not the what, and it clicked after I spent 3 hours fixing my own over-commented mess. Has anyone else had to unlearn bad commenting habits from tutorials?

2 comments

2 Comments

milar4628d ago

Ngl, the worst habit I picked up from YouTube tutorials was writing comments like 'this function adds two numbers' - which is just reading the code out loud. Real comments should document your thought process on why you chose a weird workaround instead of the obvious solution.

henry_palmer2428d ago

Started doing the same thing until I caught myself. What helped me was writing comments as if I'm explaining it to my past self who didn't know the solution yet. So instead of "this loops through the array" I'd write "had to use this weird nested loop because the database query was too slow with a standard approach." It forces you to actually think about the code and not just describe it. I also started keeping a "dumb decisions" folder in my notes where I write down why certain workarounds exist. Sounds silly but it stopped me from writing those useless comments real fast.