I think commented out code is a bad idea. Typically, it's done because a company doesn't have a proper version control system in place and commented out code makes it "easy" to back up to previous versions. Comments, in general, should be explaining why something is done, not how. If you have a particularly tricky section of code, commenting the how for that section may be appropriate. Commented out code fits neither reason and is just clutter.

Cheers,
Ovid

Join the Perlmonks Setiathome Group or just click on the the link and check out our stats.

• #ifdef ... #endif or /* ... */
• =foo ... =cut
• if ( false ) { ... }

I'm O.K., though, with commenting out blocks of code via any of

• //
• #

Since commented-out blocks of code represent issues that need to be resolved, I've adopted the practice of using a special comment "tag" that's easy to extract mechanically (via, surprise, a Perl script!) so that we can generate reports of where our code issues are during development or maintenance. These tags look like:

  #TBD(dws) version 2.0 of mummble breaks if you do this
  #      $mummble->do_this();
[download]

for $filename (@filelist) {
  ...
[download]

for $filename (@filelist) {
 # PHB doesn't want B files blurked
 next if $filename =~ /^b/i;
...
[download]

Two weeks later they decide that they really do want the b-files blurked, and you're out on holiday or have quit to preserve you sanity, and some other programmer who is not too familiar with the code has to figure out what exactly needs to be changed. It may be a poor man's CVS (which is odd considering CVS is free), but that commented out line really helps him, and he buys you a beer when you get back. The trick, of course, lies in knowing what should be commented out and what should be deleted :-)

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.

In that case, I wouldn't write out the code for the broken sections, but, instead, lay out the algorithms that didn't work and why they didn't work.

------
We are the carpenters and bricklayers of the Information Age.

Don't go borrowing trouble. For programmers, this means Worry only about what you need to implement.

I personally think it's a sign of someone who couldn't make good decisions. (Either the programmer or the manager who didn't give the programmer enough time.) That's a problem.

------
We are the carpenters and bricklayers of the Information Age.

Don't go borrowing trouble. For programmers, this means Worry only about what you need to implement.

I also leave a few useful debug messages in suitable places (I always use __LINE__ to mark where they are), commented out, but ready if I have to go digging again.

I may also leave old versions of statements lying around in case (this never happens, heh heh) the user changes their mind and wants to go back to the old way of doing things.

Now if you're talking about code that's been rewritten, go ahead and delete it swhen it's not longer relevant.

But if there's stuff that is/was relevant, comment it out and leave it.

So, my vote is, 'keep that stuff!'

"Excellent. Release the hounds." -- Monty Burns.
T. Alex Beamish, TAB Software -- Toronto, Ontario

    -- Chip Salzenberg, Free-Floating Agent of Chaos

I would add to this:

Delete unused code when it is released or goes into production.

There's some very good, valid reasons for leaving in comments in non-production/unreleased code. I find myself trying different things, adding/moving code around, and I comment as I go. Sometimes, I'll have a 1.1 cut of test code sitting inside a 1.0 version as I play around with it.

Your comment about using cvs rings true to me, and I'm a firm believer in it, but only again, in released code should you prune. If I'm working on a file, and it's going through several milestone stages working up to a release, I don't want to have to remove comments or commented code, check it in, then have others work on it, check it back out, copy back in the code from the first imported version, hack it up, take out the comments, commit it back, etc.

As an example, on one fairly complex C++ project I worked on , two of the other coders not only commented away code but also had little conversations in the comments, like this...

...
for ( i = 0; i < max; i++ ) {
   doSomething();
   // I really think this part should be removed. /Stefan 
   doSomethingElse();
   // No, it shouldn't. /Björn
}
... and even further down...
   // This code is strange. I fear it.
[download]

Cheers,
-- moodster

I just wrote some code that looks like this:

  my @logs = <LOGFILE>;
  chomp @logs;
#XXX: map { &mung_log_entry($_) }, @logs;
[download]

Now, this isn't really the same kind of "commented-out code in production" that we've been arguing about; it's more of a pseudocode comment to tell me that I've been thinking about munging up each log entry after reading them all in. In this case, I think that writing the comment as "code" is more legible (mostly in that it doesn't break up the flow of code on the page) than writing in a little note in prose:

  my @logs = <LOGFILE>;
  chomp @logs;
  # Mung up each log entry?
[download]

Eh. Matter of opinion, I guess. I think that the "code" comment more accurately conveys what I was thinking at the moment (even if it is an Evil Use of map In A Void Context -- hey, I said it was pseudocode).

Update:Yes, foreach would be clearer than map, but I've been thinking in terms of map lately.

Wouldn't an inline foreach loop be clearer as a comment (particularly for whoever might come after) than the inline map?

I know that I find it provides clearer documentation of intent. (Whether in a comment or in working code...)