Hacker Newsnew | past | comments | ask | show | jobs | submitlogin

Don't do it unless you are going to treat keeping comments up to date the same way you treat keeping the code up to date.

I've lost count of the number of times I've seen comments that were just wrong -- they applied to the code as it was written years ago, not today.

Write good code, and it should be obvious how it works. Use comments sparingly and only when things are not obvious. Update the comments when you change the code, and make sure your code review process doesn't let outdated comments slip by.

If you can't commit to the above policies, then don't comment your code at all.



Code comments that are wrong can be very useful. I've found many bugs that way. If I find a comment that states an assumption that does not hold in the code, that's the first place I analyze when looking for a bug. And very often it turns out the comment was right, but the code was wrong.


>> Don't do it unless you are going to treat keeping comments up to date the same way you treat keeping the code up to date.

This should be easy enough to verify during code review, no?


Only if the comment is very local, and not e.g. two calls up the stack.




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

Search: