I used to think comments in my code were a waste of time

I was working on a small project to track my store's inventory, just a simple Python script. I wrote it in one night and it worked, so I moved on. Two months later, I needed to add a new feature. I opened the file and had no clue what half of it did. I spent over an hour just trying to remember my own logic, especially this one part that checked for duplicate items. My friend, who knows a bit more than me, looked at it and said, 'Man, even you don't know what this does.' That was the moment. Now I force myself to write a quick comment for any tricky section, even if it's just for me. Has anyone else had a project come back to bite them because they didn't leave notes?

3 comments

3 Comments

victor8632mo ago

What kind of system do you use now to decide what gets a comment? Do you have a rule, or do you just go by what feels confusing in the moment?

foster.dylan2mo ago

What changed my mind was seeing how random my old system really was.

grant_gibson1mo ago

The best rule I have is to comment why the code is there, not what it does. The code already shows what it's doing. If a section looks odd or has a complex condition, I write a quick line explaining the business reason behind it. Like, "This check is for vendor returns that don't have a receipt." That way, when I come back in six months, I know what problem I was solving.