Hacker News Reader

Disagree! Disagree!

Having essentially the same code written in two places (code and comment) absolutely BEGS for them to get out of sync. Its why we write modules, subroutines etc - get it right once.

Comments are evil if they mention the code. They should be about constraints, the compiler, your wife, ANYTHING but the code.

View on HN

I didn't say the comment had to be describing the code in terms of what it was doing, but it absolutely should describe why something was done. If that "why" changes, then the comments should be updated.

This isn't double documentation -- it's complementary documentation. Code is the what, comments are the why. If one does not match the other, then again, that's on the programmer.

Reply on news.ycombinator.com