We have all seen comments in source files which look more like executable code than documentation.

The first line in the body of the for loop below is such a comment: you might expect to be able to remove the leading slashes and have code which compiles and runs but functions slightly differently.

What did the author of this comment intend?

for (Surfaces::iterator sf = surfaces.begin();
     sf != surfaces.end(); 
     ++sf) {
     // std::cout << "Drawing: " << *sf << "\n";
     sf->draw();
}

OK, I'm being disingenuous. I'm aware that the comment isn't really a comment, it's commented-out code. And, like any tolerant and capable programmer, by examining the surrounding context I can guess why this code has been commented out.

This article examines how to comment-out code, then describes various problems which lead to code being commented out, before finally arguing that there's often a better solution to these problems.