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

Generally, code that is removed should not be commented, precisely because it clutters the codebase (and, why would one comment on something that doesn't exist?).

Your defect tracking system or source control management tools are where such comments belong.

Answer 2

I agree that it is not a good idea to leave code removed in comments.

Code history should be viewed through a version control system, which is where old code can be found, as well as the reason it was removed.

Answer 3

I hate seeing code that's cluttered with commented out code. Delete the code and write a commit message that says why it was removed. You do use source control, don't you?

Don't litter active code with dead code.

Answer 4

It sounds like you are trying to get around versioning your code. In theory, it sounds like a great idea, but in practice it can get very confusing very quickly.

I highly recommend commenting code out for debugging or running other tests, but after the final decision has been made remove it from the file completely!

Get a good versioning system in place and I think you'll find that the practice of commenting out changes is messy.

Answer 5

I agree that it's a terrible suggestion. That's why you have Source Control that has revisions. If you need to go back and see what was changed between two revisions, diff the two revisions.

Answer 6

Nobody here has written much about why you shouldn't leave commented-out code, other than that it looks messy. I think the biggest reason is that the code is likely to stop working. Nobody's compiling it. Nobody's running it through unit tests. When people refactor the rest of the code, they're not refactoring it. So pretty soon, it's going to become useless. Or worse than useless -- someone might uncomment it, blindly trusting that it works.

There are times when I'll comment out code, if we're still doing heavy design/development on a project. At this stage, I'm usually trying out several different designs, looking for the right approach. And sometimes the right approach is one I had already attempted earlier. So it's nice if that code isn't lost in the depths of source control. But once the design has been settled, I'll get rid of the old code.