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

The recent consensus (from other discussions on here) is that the code should just be removed.

I personally will comment out code and tag it with a date or a reason. If it's old/stale and I'm passing through the file, then I strip it out. Version control makes going back easy, but not as easy as uncommenting...

Answer 2

This is one of those "broken" windows thinkgs like compiler hints/warnings left unaddressed. it will hurt you one day and it promotes sloppiness in the team.

The check in comment in version control can track what/why this code was removed - if the developer didnt leave a note, track them down and throttle them.

Answer 3

I would suggest that, yes it's good practice to comment on code that has been removed but not in the code itself.

To further clarify this position, you should be using a source code control system (SCCS) that allows some form of check-in comment. That is where you should place the comments about why code was removed. The SCCS will provide the full contextual history of what has happened to the code, including what has been removed. By adding check-in comments you further clarify that history.

Adding comments in the code directly simply leads to clutter.

Answer 4

In general I tend to comment very sparsely. I believe good code should be easy to read without much commenting.

I also version my code. I suppose I could do diffs over the last twenty checkins to see if a particular line has changed for a particular reason. But that would be a huge waste of my time for most changes.

So I try comment my code smartly. If some code is being deleted for a fairly obvious reason, I won't bother to comment the deletion. But if a piece of code is being deleted for a subtle reason (for example it performed a function that is now being handled by a different thread) I will comment-out or delete the code and add a banner comment why:

   // this is now handled by the heartbeat thread
   // m_data.resort(m_ascending);

Or:

   // don't re-sort here, as it is now handled by the heartbeat thread

Just last month, I encountered a piece of code that I had changed a year ago to fix a particular issue, but didn't add a comment explaining why. Here is the original code:

   cutoff = m_previous_cutofftime;

And here is the code as it was initially fixed to use a correct cutoff time when resuming an interrupted state:

   cutoff = (!ok_during) ? m_previous_cutofftime : 0;

Of course another unrelated issue came up, which happened to touch the same line of code, in this case reverting it back to its original state. So the new issue was now fixed, but the old issue suddenly became rebroken. D'oh!

So now the checked-in code looks like this:

   // this works for overlong events but not resuming
// cutoff = m_previous_cutofftime;
   // this works for resuming but not overlong events
// cutoff = (!ok_during) ? m_previous_cutofftime : 0;
   // this works for both
   cutoff = (!resuming || !ok_during) ? m_previous_cutofftime : 0;

Of course, YMMV.

Answer 5

I comment unnused code because you never know when will you have to fallback on the ancient code, and maybe the old code will help other people to understand it, if it was simpler back then.

Answer 6

If you are using any form of Source Control then this approach is somewhat redundant (as long as descriptive log messages are used)