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?

Example 0

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.

The first step here in finding problems in the code is to identify the problem the code is trying to solve. The discussion in the C Vu article is basically about curiosities in the way in which the C++ standard library std::istream is defined, but I will make the perhaps unwarranted assumption that what the problem the code is really about is not the uses of std::istream, but rather, more generally, how to write a read routine that can effectively and safely capture data from an input stream. Actually as the first problem below illustrates neither of these issues can be effectively addressed without the other.