Recently I wrote some code that included a comment along the lines of $foo = ... I commented it out because $foo was not actually being used in that section, and having it uncommented would (to me) suggest it is being used. I included it as a comment because I believe there's a good chance that future modifications will use $foo, and it was much easier to add the calculation for $foo while it was still fresh in my mind.

Some may disagree, but I don't think what I did was so bad. Commenting out code is, in my opinion, like many other practices which are generally a bad idea but from time to time work.

A better example came up last week at the Amsterdam.pm meeting, when the person giving the talk was asked why he had implemented a portion of his project in one way rather than another. The question was quickly answered when he displayed the code, which contained not only the code that was in production, but also two other ways of doing it along with explanations of why they didn't work.

I doubt I'm the only one who has looked at something I wrote just the day before and wondered why I did it that way. In such a case, code comments can prevent the same mistakes from being repeated, either by someone else maintaining the code, or even by the original author with a faulty memory.

Update: In this particular case, it wasn't algorithms which were tested, but rather system calls with different combinations of arguments. Because it was the syntax that was being explained, code seems a logical way to document. That's certainly common--just consider the pseudo-code often found in the synopsis of modules. Of course, the code still required text explaining what the problem with each approach was in order to be of any use.