Commenting code that is removed [closed]

Question

Is it a good practice to comment code that is removed? For example:

// Code to do {task} was removed by Ajahn on 10/10/08 because {reason}.

Someone in my developer group during a peer review made a note that we should comment the lines of code to be removed. I thought this was a terrible suggestion, since it clutters the code with useless comments. Which one of us is right?

Answer 1

There's a general "clean code" practice that says that one should never keep removed code around as commented out since it clutters and since your CVS/SVN would archive it anyway.

While I do agree with the principle I do not think that it is an acceptable approach for all development situations. In my experience very few people keep track of all the changes in the code and every check-in. as a result, if there is no commented out code, they may never be aware that it has ever existed.

Commenting code out like that could be a way of offering a general warning that it is about to be removed, but of course, there are no guarantees that interested parties would ever see that warning (though if they frequently work with that file, they will see it).

I personally believe that the correct approach is to factor that code out to another private method, and then contact relevant stakeholders and notify them of the pending removal before actually getting rid of the function.

Answer 2

I agree with you Andrew; IMO this is why you use version control. With good checkin/commit comments and a diff tool you can always find out why lines were removed.

Answer 3

You should delete the code always.

As for being able to see old/removed code, that's what revision control is.

Answer 4

The question is, why do you remove code?

Is it useless? Was it a mistake to put it there in the first place?

No comments needed from my point of view.

Answer 5

I think it's pretty useless and make the code less readable. Just think what it will be like after some monthes....

// removed because of this and that
/* 
      removed this stuff because my left leg...
*/
 doSomething();
// this piece of has been removed, we don't need it...

You'll spend half an hour to find out what's going on

Answer 6

If you are in the middle of major changes, and need to make a fix to existing functionality, commenting out the future code is a reasonable thing to do, provided you remark that this is future functionality, at least until we have futures friendly source control systems.