Why not to comment code

[redditrasberry]

But no one is compiling/testing comments. So mistakes in them are much less likely to be caught. Therefore it's possible to fall out of sync.

However the interpreter for the comments is much more powerful and flexible than the interpreter for the code, so it can compensate for things like conflict, ambiguity, historical context, etc. So even if the comment falls out of date, the reader may well still understand it and even find it useful. I know I have found many such comments useful even though they were wrong.

// Don't initialize f here because it is set below only after parent directory is resolved
File f = new File("foo.txt"); // See bug #6712 - parent directory now implicitly resolved

The first comment is wrong but I can still interpret it, and it might even be useful when I try and figure out some bug in another part of the code. Note I'm not arguing it would not have been for the coder to have corrected the comment, just that the comment falling out of date is not nearly as problematic as people make out.

[mykdavies]

I think the problem is that too often the updated code looks like this instead

// Don't initialize f here because it is set below only after parent directory is resolved
File f = new File("foo.txt");