I thought writing long comments in my code was the best way to learn

A friend looked at a project I made and said my comments were just repeating what the code did, like 'this line adds the numbers'. She told me to write comments that explain WHY I made a choice, not WHAT the line is. I changed my style last week and now my notes say things like 'using a loop here because the list length can change'. It makes me think more about the plan before I type. Has anyone else gotten advice that changed how they write their code notes?

3 comments

3 Comments

jade3281mo ago

My friend gave me that exact same advice last year and it was a total game changer. I used to write whole paragraphs explaining what each variable did. Now my comments are way shorter but actually useful when I come back to the code later.

evan_burns951mo ago

Yeah, the part about comments being useful later is so true. I had the same problem where my comments just repeated the code. What helped me was asking "what would confuse me in six months?" I only write a note now if the reason for doing something isn't obvious, like a weird workaround for a bug. It saves so much time when you're trying to remember your own logic.

jamesfox1mo ago

Totally changed my own comment style after a similar talk. Started forcing myself to write the reason right above any tricky bit, even if it feels dumb at the time. The real win was realizing my future self has no memory, so I note down why I picked one approach over another. It turns comments from noise into a little breadcrumb trail for when I'm totally lost later.