Hacker News new | past | comments | ask | show | jobs | submit login

I agree it's a lame excuse not to document code, however there are just some parts that just changes way too often by multiple people where outdated comments can actually lead you astray. The stuff I touch doesn't change often so I'll comment to explain the weird and ambiguous looking parts.



I'm not saying you have to document each line of code with equal rigor. In fact, there's an art to knowing what to document, and like most arts, you get better at it over time. Sometimes I feel silly about what I've documented and what I've neglected, but that's OK. I learn.

The "code changes way too often" excuse is basically a restatement of the myth that I wrote above. Yes, code changes over time. It's pretty easy to change the comment with the code, when necessary. The team members who don't do this aren't doing their jobs.

But at the end of the day, even if code deviates from comments that's still fine. Having an outdated, well-written comment is a historical record of what the code was supposed to be doing. That's useful.




Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: