I used to skip commenting on code because I thought it was a waste of time

For months I never added comments to my JavaScript files. I figured the code should speak for itself and anyone reading it would just have to figure it out. Then last week I went back to a project I wrote in January and spent almost 2 hours trying to understand my own logic. Now I leave at least a short comment on every function. Has anyone else had to reteach themselves their own code?

3 comments

3 Comments

charlescraig4d agoMost Upvoted

It's just code comments, not a PhD thesis. Spending 2 hours figuring out your own code sounds more like a design problem than a documentation problem.

uma_williams4d ago

The thing nobody is talking about is how bad comments can actually make onboarding new devs way harder than no comments at all. I've seen teams where someone wrote a wall of text explaining their "clever" algorithm, but it was outdated by three refactors and now it's actively misleading people. You're better off with zero comments if the code itself tells the story through clean variable names and small functions. Two hours to figure out your own code is rough, but I'd almost rather have that wake-up call than rely on comments that might be lying to me about what the code actually does. Good design beats good documentation every single time.

tessa_murray4d ago

@uma_williams your point about outdated comments hits hard, I've been burned by that exact thing.