Why Comment-Out code?

The obvious answer – to stop it from executing – begs the further questions: Why should the code not execute? Did it ever execute? Will it ever execute? There are several possibilities:

The commented-out code has been superceded by something better, but the author of the new code wants the old code to stick around for a while, perhaps as a reference, perhaps out of historical interest, or perhaps because the new code might not turn out to be better after all.
Commenting the code out appears to fix a bug, but noone understands why – hence the old code is left in comments.
The code was commented out during an experiment, maybe an attempt to reproduce a bug, and should never actually have been checked-in in such a state. In other words, a bug has been introduced: in fact the code should still be executed.
The source file belongs to a third party library which has required modifications to work in-house. The lines which have been commented out represent the source code in its original form.
The commented-out code produces irritatingly verbose debug diagnostics which needed silencing.
The commented-out code represents work-in-progess which the author has sensibly checked in to the source repository for safe keeping.

These are all reasons for turning code into comments, some more reasonable than others. Categorising our examples: Example 0) appears to be silenced debug, Example 1) work in progress, and Example 2) a hacked-up experiment – though we really cannot be sure. Example 2) might equally well remove the symptoms (if not the cause) of a bug and Example 1) might represent a superceded method.

The important point is that unless the author of the commented-out code explains what's intended, it is impossible for future readers to accurately guess. How, then, should the author explain? With a comment!


for (Surfaces::iterator sf = surfaces.begin();
     sf != surfaces.end(); 
     ++sf) {
     // std::cout << "Drawing: " << *sf << "\n";
     // Work in progress. Surface stream output not yet implemented.
     // Tom Guest, 12-Dec-2003.
     sf->draw();
}

Depending on circumstance, the comment might read:


// Do not inflict verbose debug output on everyone.
// Tom Guest, 12-Dec-2003.

or even:


// Commenting out the above line of code appears to cure the
// random crashes reported as PR666. I am not yet sure why,
// but am leaving the code commented out while I investigate.
// Tom Guest, 12-Dec-2003.

I have included an explicit name and date in the comment – redundant data, strictly speaking, since they duplicate information held in the source management system – because I do not intend the code to persist in its current state. The comment has a sell-by date. Anyone reading it will immediately understand what's going on and who to hassle if they don't like it.