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

As the lone dissenting voice, I will say that there is a place for commenting out code in special circumstances. Sometimes, you'll have data that continues to exist that was run through that old code and the clearest thing to do is to leave that old code in with source. In such a case I'd probably leave little note indicating why the old code was simply commented out. Any programmers coming along after would be able to understand the still extant data, without having to psychically detect the need to check old versions.

Usually though, I find commented out code completely odious and I often delete it when I come across it.

Answer 2

I also think it's a terrible suggestion :)

You should use source control and if you remove some code you can add a comment when you commit. So you still have the code history if you want...

Answer 3

There are some (rare) situations when commenting code out (instead of deleting) is a good idea. Here's one.

I had a line of code that seemed good and necessary. Later I realized that it is unnecessary and harmful. Instead of deleting the line, I commented it out, adding another comment: "The line below is wrong for such and such reason". Why?

Because I am sure next reader of the code will first think that not having this line is an error and will try to add it back. (Even if the reader is me two years from now.) I don't expect him to consult source control first. I need to add comment to warn him of this tricky situation; and having wrong line and the reason why it is wrong happened to be the best way to do so.

Answer 4

Depends on the reason for removal.

I think of comments as hints for people maintaining the code in the future, if the information that the code was there but was removed can be helpful to someone maintaining the code (maybe as a "don't do that" sign) then it should be there.

Otherwise adding detailed comments with names and dates on every code change just make the whole thing unreadable.

Answer 5

It's useful when debugging, but there's no reason to check in code that way. The whole point of source control is being able to recover old versions without cluttering up the code with commented-out code.

Answer 6

In almost all cases old code should of course be removed and tracked in your RCS.

Like all things though, I think that making the statement 'All deleted code will ALWAYS be removed' is an incorrect approach.

The old code might want to be left in for a miriad of reasons. The prime reason to leave the code in is when you want any developer who is working in that section of code in the future to see the old code.

Relying on source tracking obviously does not give this.

So, I believe the correct answer is:

-Delete old code unless leaving it in provides crucial information that the next developer in the code would require. Ie, remove it 99% of the time but don't make a draconian rule that would remove your ability to provide much needed documentation to the next developer when circumstances warrant it.