Do you leave historical code commented out in classes that you update?

Question

When you need to obsolete a section of code (say either the business rules changed, or the old system has been reworked to use a new framework or something) do you delete it from the file or do you comment it out and then put in the new functionality? If you comment it out, do you leave a note stating why it was removed and what it was originally intended to do?

I ask mainly because I've done a lot of contract work for different places over the years and sometimes it's like excavating a tomb to find the actual code that is still being used. Why comment it out and leave it in the file if source control has a record of what used to be there? If you comment out a method do you also comment out/delete any methods that were exclusively used by that method?

What do you think the best practices for this should be?

Answer 1

I always delete old code - I don't like messy code.

There should always be a record with source control.

Answer 2

if your files are under source control, I would say never leave the commented-out code in there.

Answer 3

I prefer to delete it. That way, it doesn't clutter up the current codefile, and anyone who cares can look it up in version control.

Answer 4

You're about to hear the sound of 10,000 developers admonishing you to use source control.

I worked as a FoxPro programmer for 10 years and comments with notes were good enough.

Answer 5

Absolutely not. Commented out code is deleted code. Source control has the file's history as well as the comments to the code changes (why this particular chunk was deleted).

Answer 6

Absolutely, the code should be deleted instead of commented-out. Revision control is where historical code belongs. Code is insanely unreadable when (for instance) every third line is commented out.

Answer 7

Funny you ask that; I just finished removing some obsolete code (and comments!). I find it quite pointless given source control.

Perhaps it is useful to detect something like yo-yo coding where you're changing one piece of code back and forth to meet different requirements...but I rely on test cases for that. If someone wants something to work some way, add it in the test case and explain why the test case exists. I don't understand why folks would use commented-out-old-code for that.

Answer 8

I delete it. It's in source control, and I comment on all check-ins so that later I could refer to it's history.

Answer 9

I take out the code and comment on it when I check it in. That's what your source-control system's good for. You can always do a look-up on that section later.

Answer 10

The official answer I get is to remove it.

The reason you'd leave the old code in place and commented out is generally because you want to be lazy and copy/paste variables names, or see how you did it before, or just in case you need to switch back to the older way of doing it someday, etc.

I didn't say they were good reasons.

Answer 11

Delete delete delete delete. You are changing the code for a reason (hopefully a good one), there is no need to leave a history inside of the code file of what it used to do. People have a hard enough time figure out what it is currently doing!

Answer 12

We are in an age when it is easy to setup a source code versioning system. If code is worth keeping, Then check it in, it is saved now and forever. If you want to replace it with a new version delete it,

• The old version will be around if you need it.
• Commented out code makes code hard to read since it still looks like code, and takes up the same space as real code.
• After a few changes to the original code, the commented out version is way out of date

I once saw a function that had over a hundred lines of commented out code, when I removed the commented out code, it was only 2 lines long.

Answer 13

I tend to think that the source control system is the right place for viewing historic code changes, meaning that historic code should be deleted from the source files and appropriate comments should be added to the checkin.

That said, there seem to be a number of dev shops with pretty shoddy source control practices and I can imagine people arguing that in such environments historic code should be commented out. However, best practices in such environments would be to sort out their source control system, so it could be said commenting out historic code is never best practice but sometimes an excuse for bad practices.

Answer 14

Always delete old code. If you're using a decent SCM tool then it's simple to view changes. My favourite is Perforce which offers a fantastic time-lapse view of changes.

Answer 15

I only do this very, very rarely. Occasionally, there's a clever fix or workaround where the original solution, which you'd think would work, just didn't. If the original code is small, say less than 10 lines, I'll leave it there along with an explanation why we are doing things the way we now do.

In nearly all other cases, this is the job of source control. Use it. Love it. Clean up the junk.

Answer 16

Source code control makes this a non-issue; commented out code is dead code, and dead code should be dropped. If it turns out that this was a mistake, revert to a previous version and fix it up from there.

I find that random commented-out bits of code are often a symptom of programming by coincidence, which I don't like.

Answer 17

I'll leave it in while still testing, but then delete it as I come across it later.

Experimented with immediate deletion, but reverting from the repository is MUCH slower than simply uncommenting again. Deleting costs the same amount of time whenever it's done. The source control system does give the safety net/confidence needed to pull this off though (you have to be perfectly confident that you can delete any commented code).

Answer 18

I aggree with you. If you are using a version control system, there is no need to leave in commented code. Always make the code as clean and simple and easy to understand as possible. Lots of old unused commented out code is a lot of extra noise.

There are times to maybe leave the commented code in, such as if your testing a bug fix, but long term get rid of it.

Answer 19

I've actually worked on some applications where old code as not removed, but instead just commented out and I found that it tended to actually increase the time to implement bug fixes and new features because you hand to dig through all of the text to find what to edit. In some cases having the old code in place was useful in debugging because you were able to see how a thought process changed; however, I personally find it a bit more useful if there is a comment at the top of the file discussing revisions that were done along with when they were done and the revision number if it is available.

Granted most modern IDEs do allow for code folding which can get the commented code out of the way, it just seems easier to look at the current code and compare it against the old code in context from source control history than trying to piece everything together on your own.

Answer 20

I usually remove the extraneous code after a period of time--usually throughout testing, but removed before delivery. This makes it easy to grok history of a chunk of code. Depending on how much is changed, looking at the source-control history may not be immediately helpful. If functions were renamed, re-ordered, etc it may take a lot of effort to map between the old code and the new code...

Leaving the commented code in, temporarily, makes browsing the repo history a little easier. You can also use code folding/regions/etc to make this a little cleaner--and since its temporary, it avoids those religious arguments about whether code folding directives are good or evil.

If I want to remove it immediately, I usually comment out the code, put a note, check-in, delete code, then check-in again. Again--this is mostly to retain a clear history of what the "new" code replaces.

Answer 21

I believe comments in code to be excess noise in general. Like you said digging code out of source control can be tedious, but probably far less dangerous or annoying than useless commented code littering through out the actual code base, with no one around who understands why it is there or why it hasn't been removed.

Of course there are always pragmatic reasons why you may have commented out code, and every rule should be overlooked when the right situation arises. For example it may be more work to remove code completely if it just doesn't make a release, than to just comment it out knowing full well that it will be used the following day/week etc

Answer 22

If you're not using Source Control, start.

If you can't start and you need to comment out the code for some reason, you better maintain it when you maintain the non-commented out code too. I'd say the odds of that are low so the utility of the commented out code decreases exponentially over time. Delete it.

Answer 23

I do when writing an emergency production patch, but generally remove it when I have time to properly test my new code.

Answer 24

If you're using a version control system try to keep the code cleaner as possible, the version control would have to keep your history of changes. But if you don't use version control, the best I think (only did once, I always use version control) is to leave a comment but not the code, you have to know that a certain block of code was erase, but not need to keep it; but always is a catch, do it only and only if you know you'll never need that code.

Answer 25

Comments written in English (or whatever language the development team communicates in) or pseudo code and version control history would always be my priority over leaving old, unused code behind, in or out of comments. There are, however, four situations that I can think of when I might leave the code in.

1. If I expect part of the code to have use in the very near future.
2. If there was no version control for the file, and there was a desire for the history.
3. If I wasn't confident the code was obsolete, and needed to confirm this but was unable to talk with those who might know right away.
4. The code is "obsolete" because it was removed due to QA constraints or market research concerns, but I was confident it would work properly and provide benefit if enabled.

In all of these situations, I'd make sure to add English comments with the obsolete code, and be sure the version control logs also explain why it is still there but not in use.

Answer 26

I delete it: Keeping the history is the task of the source code control system!

There may be one exception to this rule: if the code is very complex, and an simpler solution may be obvious, I may leave the old code (if it is terse) to demonstrate what does not work!

Answer 27

Well, on the mainframe, we don't have those fancy things called classes.... Or at least not in the version of cobol we use. But, as for commenting code rather than just deleting it, I usually delete it, but then we also have version control software that keeps a copy of each change, back 10 years or so...

Answer 28

A while ago I worked for a pretty big project that didn't use sourcecontrol. I tried, several times, to introduce source control, but it didn't happen until (finally) the software was delivered to the client, taken under maintenance by our company, and the client demanded source control.

Anyway, since there was no source control, nobody dared throw complicated code away. And it was terrible -- in some modules, over half the code was commented out. Worse, they were all block comments, so when grepping through the code for some string, you could find a lot of code that would turn out to be in some long comment.

Conclusion: throw unused code away even when there is no source control system -- if you accidentally thow away something valuable, writing it again will lead to less loss of resources than keeping loads of garbage code.

Answer 29

Further to the answers here. If the code is no longer useful, then definitely delete it. BUT, sometimes it can be useful to keep old code as a reminder of "how not to do it", or just useful reference information. If you do decide to comment out old code, ALWAYS make sure you add a comment explaining why it is commented out.

Answer 30

If I'm working in Visual Studio and it's a temporary change (i.e. I'm trying a new version), I keep the old one untill I'm happy (cause I don't have SVN yet).

In Netbeans, however, where I do have SVN built in and a remote SVN server to work with, I don't bother. I just restore from previous checkins if I have to. Having source control een for hobby projects, works wonders.

Answer 31

Always delete old code. I added a Perl::Critic policy that specifically checks for commented-out code and warns if it finds any.

Answer 32

I did when I was young and stupid.

These days I regard commented-out code as rot and nuke it from orbit with prejudice. Everything I do is in source control, so if I really need it back I can dig through source control until I find it.

Answer 33

I always delete old code.

It's not of interest how a method or class looked like in the past. It's more important to see and understand the code like it is now. However, if older code might be of interest nevertheless, you still have a repository as a backup! Good comments on your commits will be useful to find those deleted code parts.

Answer 34

I prefer to delete the old code and keep it in source control, but will leave it in commented sometimes, if it is good information to help figure things out in the future.

Answer 35

If the code is under source control, I will delete the relevant lines.

If the update is initially in a live setting, then that version will have the relevant code commented out to enable a quick rollback.

I'm talking here about a situation where a live platform is having problems. The edits on the live platform should always be done via the commenting method.

cheers,

Rob

Answer 36

I leave it in there for a while - as nice as it is to go back to an old version via source control, it's still quicker to just un-comment the lines I need again. Sometimes it serves as a clue: "you did it this way for a reason..."

But yeah I periodically go through and do "spring cleaning" and purge it all. It's actually kind of fun.

(the fact that I find this fun is sick, and is part of the reason people like me are on this site)

Answer 37

I try to get one check-in with the code commented out, and then remove it altogether. I hate big chunks of dead code kicking around my screen.

Answer 38

use source control, delete old crap

Answer 39

There's no point to keeping it around. If you really needed to know what it looked like in the past, that's what source control systems are for.

Answer 40

I never leave obsolete code around.

The one exception is if I'm doing major changes. In that case I sometimes leave old code commented out, but as soon as my changes or fixes are done, the old code is gone.

Everything I work on is insource control, if I ever need old code, I can revert to an older version.

Answer 41

I delete historical code. That's was a source code repository is for.

Answer 42

//No, I don't.

;)

Answer 43

Hellno. Anything that could possible lead to confusion goes into oblivion.

If is suspect any future need to refer to that code or undo changes, and i'm not working with a subversion (or other) repository, i may paste the dead code into a file like old_code.cpp kept in an attic/ directory.

Answer 44

I keep the old code, because most of the times it gives inputs as to how a particular things was changed and the error conditions it resovled. I have seen a particular query that was changed 4 times to and fro, because when one condition occured, it changed to other, and when that occuered it changed back to original. Since this is historical code, may users who are changing it would not understand all the various business conditions. Leaving the old code servers as documentation. If the code get too heavy with commented code, i then do a code clean-up and delete all the old code, and mention the version where this would be available.

Answer 45

It depends on the situation. If it's a bug fix I'll remove the code and rely on source control to have the older versions. If it's a fix because a customer changed their mind (requirements), I comment the old code and add a comment describing why the change was made and what customer stakeholder requested the change. Makes it easer to say question when they decide they want it changed back.

Answer 46

1. Verify that version control is in use. When there is no version control, I at least add it to Tortoise SVN. This tool can be used from windows explorer and is VERY flexible.

2. Delete the old code with confidence!

3. Add relevant comments.

No matter how disciplined your dev team is or how well you document and promote the procedure, there will always be variations. And all of us coders seem to be in agreement that it is messy.

Answer 47

I'm definitely in the delete it, then commit it immediately, with a commit message which states why the chunk of code was deleted, camp. Source control has the previous code, and the commit message now states that a chunk of code was deleted. Anyone who wants to look for it can find it if they are competent with the source control system.

Answer 48

Generally I delete, but in special cases I use this pattern:

if (false) {
    // Dead code goes here..
}

This is better than #if 0 as the code will still get compiled (so is likely to be maintained when the framework changes).

Additionally for some types of dead code it's nice to have it visible, and not hidden away in source control. Extra verbose debugging stuff is an example, it can be nice to have it there ready to be enabled when needed.

Note that some compilers are too clever and complain about unreachable code, so with some compilers the false needs to be replaced with a more complicated expression that it doesn't realise is compile time constant.

In general though the rule is to delete, I only use this for certain types of dead code that I want to keep visible.

Answer 49

Delete all old and unused code.

Your source control will have command like 'annotate', which will tell when some piece of code changed in the version history, how and who did the change.

The more valid and currently working code you can fit on single page, the better overview you get and it is easier make changes, find bugs and so forth, than if you need to scroll through a lot of commented out code that brings no value to you.

Even if you are not using source control systems, it is preferable to delete unused code, because it is much easier to write it again, than to maintain the current code with all the garbage in it. Writing more code, adding features or extending some working code is usually matter of minutes, while debugging badly maintained code is matter of hours or days.

Answer 50

I was taught to delete the old code because leaving it there commented out makes the program as a whole more difficult to read. This isn't as big of a problem with smaller programs, but in larger systems, looking for working code becomes problematic when you have code commented out, especially when you have more code commented out than actually working.

If you need to keep the old code around for a little while, then this isn't a problem if you're using version control (you are, right?). If there is no version control and you can't set any up, then I think it would be wise to keep the old code, or an older version of the file, someplace separate from the running code and perhaps leave a comment stating where the old code is if its needed.

Answer 51

If I have the luxury of version control I'd just delete old code, if not I comment out with a short explanation to why. I also usually document the change and reasoning in a changelog.

Answer 52

In general, I delete it. There is one special case when I comment it out: If that piece of code seems like a good idea, but isn't. This way, nobody will likely put it in again at a later moment. Example:

try
{
  setUpLogging();
}
catch (Exception e)
{
  // handleError(e); BAD IDEA, logging is not set up!
}

Answer 53

This is a habit I picked up before I ever even heard of 'version control'. It can create a giant mess over time and I don't recommend doing it.

Answer 54

Definitively delete it. Source-control does the rest. If you need the feature again, reverse merge it in. You won't want to do that manually over x files for more complex changes.

This has also the advantage that you can merge the removal on other branches and this "feature" or "feature removal" gets isolated in one change-set. You do not have this information if you just comment-out... I do not see any good reason to keep the code commented out, plenty for getting rid of it.

Answer 55

Delete it. Get it back from source control if you ever need it. Actually at the point you decide to delete, it may be a good time to check it in and then delete.

Answer 56

case #1: If you have source control, then delete it.

case #2: If you don't have source control, then get source control and see case #1 above.

To me when I see commented code, I think to myself that the developer that made the change wasn't sure he was doing the right thing. He should spend the time to make sure instead of having a backup policy of having the commented code to revert back to. And if in the end you aren't sure if you're making the right change, put a comment that describes what you changed and why you're unsure if it's the right way, and delete the code still. Don't comment out the block of code.

Code is hard enough to read and follow as is, you don't want to clutter code and make it even harder to understand what it's currently doing by having big blocks of commented code. If someone needs to look at the history he can look at the history via the source control.

sometimes you need to add the feature back in and the developer adding it back in may not know to check source control history

That's what logs are for in source control systems. They allow you to search comments and file history. Also this seems to be more of an organizational concern. You could assign tasks to more appropriate developers or have discussions within the team. The person assigning the task should know who to assign it to or what to reference.

Also if you think you'll be adding it back in, consult your manager and make sure you are making the right change for what they want to do.

If you really think a big part of the code will be reused again, you can branch or tag your repository and then make the changes. You can reference back to that branch or tag later.

sometimes the code represents unique functionality that can be a handy reference, seeing it all in one place can help provide clues to deciphering the active code.

Create some kind of internal knowledge base or reference with the insightful code. Having logic where it doesn't belong anymore makes code harder to read and understand.

Answer 57

Delete it. The less code it is the better is. We always keep daily builds and change-logs of our projects both in and outside of the source-control. Whenever we want to refer we just get the right build and use the code.

Answer 58

On recent experience, where a feature was requested to be removed, only for it requested to be put back 2 weeks later (client used to be indecisive, now they're not so sure...), I'd comment it out, then delete it x days/hours later.

Commenting out initially also has the advantage where there's over bits of code that were relying on that block/method, it's easier to see how they need to be refactored.

Don't forget to delete it though, otherwise the code gets crusty very quickly.

Relying on the cvs only works if everybody on the team is savvy enough. Particularly with web apps where you're working/co-ordinating with designers, html/js devs, and junior developers, this assertion can fail...

Answer 59

IMO:

Comments are used to describe (comment) on a particular part of code. Not as a way of disabling code from functioning.

Answer 60

1. Delete it
2. Delete it
3. Delete it
4. Please. Delete it.

Commented code is not only obsolete and unnecessary, it is also confusing (and scaring, for me)

Answer 61

While I agree that most of the time deleting it is the better choice, for all the reasons noted, I think there are exceptions. Yes, your library will still have the deleted code if you need to get it back. But how do you know it was ever there to make you think to check the library? If it's a matter of, "Two weeks ago the user said to remove this and now they say to put it back," sure, any decent library will allow you to recover the deleted code. But sometimes when you're reading the code, trying to understand it, a commented-out block can make clear, "This is how it used to work, but we changed it."

Like, just today I was working on a program that the user says is not behaving as they think it should, and I saw a commented-out line of code that would make it behave the way the user now says they want. So I immediately know that it used to do that. Now I know to check, Who changed it and why? Without that, yes, I could have searched the library for recent changes, but I would have had no clue what to look for.

That said, I heartily agree that programmers comment out large blocks way too often, and most of the time it just clutters up the code.

I don't have any good general rule for when to delete and when to comment out. But seeing old code is sometimes useful.

Answer 62

The problem with the argument if the feature needs to be added back in is that by that time the rest of the code might have moved on, and if anyone then just uncomments this bit of code, it might no longer work as expected.

Usually the features will never be put back in again anyway, but the files will grow and grow until more than half the file is commented out code that will be really confusing if you ever have to look at it without syntax highligting for some reason.

Answer 63

One situation where keeping the code may be desirable is when you may want to repeatedly switch between two versions of code for various reasons. For example, there may be a version of a routine which is too slow for production use, but is known to be very robust, and a version which is much faster but relies upon certain things working correctly. If things start acting strangely, it may be useful to temporarily switch to the slow-and-solid version and see how that works.

In a typical PC environment, one can probably handle such a distinction at run-time, though one might leave the slow-and-solid version out of non-debug builds. In embedded systems work (which is much of what I do), it's often better (or even necessary) to make such distinctions at compile time. Note that I would use #if/#else to enable/disable code in such cases rather than selectively commenting it out. Commenting out blocks of code of non-trivial length is ugly.

A second factor, related to the above, is that an unacceptably slow way of doing things may be easier to understand than a faster way. So it may be helpful to have a comment in the faster (production) version of the code which says "Should be equivalent to the above (slower) method". The slower version of the code may be obsolete, but may nonetheless aid in understanding the faster version.

A third scenario where I uncomment rather than delete things is when controlling build-time options. For example, in one of my projects I have a file called aadebug.h which contains stuff like the following:

// #define MASTER_DEBUG
#if MASTER_DEBUG
// #define QQ_RAPID_KEY_TIMEOUT
// #define QQ_FORCE_BAD_READINGS
// #define QQ_DROP_SOME_READINGS
// #define QQ_SKIP_PASSWORD
#define QQ_ENABLE_MOTOR_TEST_MENU
#endif

Various bits of code to test various things will be selectively enabled with #ifdef's; all such bits of code are controlled in file aadebug.h. The main screen display code includes

#ifdef MASTER_DEBUG
  pcshow(VR5,5,64,"NOT FOR PRODUCTION");
#endif

so that any debug versions of code can be readily recognized as such. If after testing out a piece of code I decide the stuff to simulate errors (or whatever) is no longer needed, I'll delete the #ifdef's from the code and then delete the #define in aadebug.h; as long as the #ifdef's remain in the code, however, I'll leave the #define in aadebug.h (but commented out) as a reminder to the test code elsewhere.

Answer 64

Is it better to comment out unneeded code or delete it?

Assuming source code control, I sometimes delete, but my most frequent answer is first one, then the other. That is, first I will comment something out, but let it stick around for anywhere from a few commits to a few weeks. Then eventually I will delete it entirely. I do this only using comment to end-of-line conventions, so that anyone reading the code instantly sees that it is commented out.

My primary reason for not deleting old code immediately is that I work with others, and not everyone is a source-control ninja. (I myself sometimes have trouble using gitk to figure out what happened or how things used to be like.) A large block of commented-out code is a good way of communicating to other project members that something important has happened.

Another hammer in my toolbox is to change the names of old functions or methods so that they still compile but are not used. I use this tactic when I think the code should be retired, but my colleagues might disagree, and until a final decision is made, I want everything to compile. Yet another trick is to migrate moribund code to a separate file.

Finally, of course, old commented-out code has to be retired (fully deleted) periodically so it doesn't clutter up the source.

Summary: There's no one right way to deal with code as it ages and dies. There are plenty of useful tactics, and you should pick and choose according to the code in question and your particular situation. But in the long run, dead code should be deleted, remaining only in the source-code control system from which it can be resurrected if needed.