Alternatives to commented out code for historical purposes

Question

Does anyone have a valid alternative for using commented out code checked into the repository for findability reasons?

The reason I ask is because I had a discussion with a fellow developer recently on checking in code that is commented out. My stance is that commented out code should never be checked into our VCS since it is not technically part of the codebase, and thus annoying cruft which does not deserve the bytes it is taking up, so to speak.

His counterpoint was that some of the commented out code he checked in still illustrated some work he would like to fix in the future (in this particular point the commenting out occurred 2 years ago, but that is besides the point). He wanted to keep it in the codebase so he could easily find it, and even though it would not currently compile, it still showed in global lines the correct way to solve it.

In the end he agreed, sort of, that commented out code does not belong. But when we were thinking of possible alternatives to his we came up pretty short.

The only options I could think of were:

• Wiki: just paste it somewhere on a wiki. Drawback of this is that it will get mixed with other non-code related wiki content which may make it hard to search on it.
• Index all VCS revisions: This is largely theoretical for me, but are there systems which make a codebase and its entire history searchable?

Does anyone know of/use any alternatives? Both my options sound like more work than it's actually worth, but that may be skewed by my reasoning that commented out code is worthless anyway. I'd hate to have to go the "Hey, if you don't have time to fix it now it's not important enough to stay in the codebase anyway" route (but I will if there are no viable alternatives).

Sorry for the horrible title, I could not come up with a better one

Answer 1

sounds like your friend should create a branch and try out his 'improvements' there. You would be easily be able to diff between this improvements branch and current source to get a clear representation of the changes that he is intending.

Answer 2

I understand that the code is no longer used but it contains ideas that could be interesting for the future.

I'd store in the control version system but I'd keep it in a separate folder, something like removed-code-to-review-later. Then, I'd remove it as I review it.

Answer 3

Branching can be useful here. One model of using SCM is to create a branch for each feature. This is popular when branch merging is painless - an ease no afforded by all SCMs ... :-)

The idea is that each feature you work on has a dedicated branch, and is worked on entirely within that branch. When the feature is complete, working, tested, documented, and won two olympic golds etc.. the branch is then merged into the trunk. Alternatively, the branch stays open indefinitely if the feature is never completed or abandoned etc. But the code then remains visible, ready to be picked up by someone, someday.

This is a good way to store "work in progress" - because the code is branched you can freely check in the tentative code. It doesn't need to be commented out since the work in progress changes are only in that isolated branch, nor does it even need to compile, since these branches are usually not migrated into continuous integration until they've reached a level of maturity.

Unlike commented out code, these tentative code changes are visible and searchable, ameanable to code analysis tools, refactoring etc.

In some environments, the feature and it's branch may also have an associated change ticket or issue tracking id. This ensures that significant changes don't get lost, and provides a means of prioritizing and organizing the various features, from fixes for showstoppers down to experiments in implementing something a different way that probably will never see the light of day.

As to searching, some SCMs have a search front-end. For example, SVN has SVNSearch - http://sourceforge.net/projects/svn-search/. There is also svnquery, which can search history as well as head.

Answer 4

In my experience, the biggest reason for checking in commented out code is that developers hate typing so much that they would rather keep the unused code handy just in case they ever need to type a similar fragment of code in the future.

Your case is a bit different, but I still say "use it or lose it". If the commented out solution fixes something important, then that would be a good motivation for finishing it. It's easy to spend more time explaining why something isn't quite right and "how we were never given the time to fix it" than it would take to do it.

That last point is based on the assertion that developer time is non-linear, and that getting started on something that you're motivated to do delivers much more value than "X hours booked to project Y" every time.

There are version control systems that are very good at creating and merging branches. Mercurial, git, etc. would all be capable of doing this. Even if you don't use one of these as your main VCS there's nothing to stop your colleague creating a local repository to keep his experiments in.

Answer 5

In some scenarios it is a good idea to document solutions to some complex / unique problems, for reference purposes. I don't think it should belong in the code though. IMHO I think a Wiki of some sort is the best option.

If you haven't used the code in the past 2 years will you ever use it and if you do should you still be using code that is 2 years old? If you ever need to add that logic again to the code it may be better to write it from scratch as most likely over that time period things would have changed, you would have learnt a lot, additional resources would be made available to you, etc

Answer 6

some of the commented out code he checked in still illustrated some work he would like to fix in the future

Then he should open a low-priority ticket in your bugtracker, describing that what he would like to fix, and add the presently commented out code as a comment to that ticket. Now he can assign that ticket to himself and no one else will ever be bothered by it.

Commented out code is like any other comment: if not properly maintained it tends to lose its consistency with the code and thus its usefulness.

Answer 7

Your statement "Even though it would not currently compile, it still showed in global lines the correct way to solve it."

<>

Your statement "my reasoning that commented out code is worthless anyway."

I do not see the harm in leaving the comments, as they will often provide insight to future developers on what the original developers intent was, and any current limitations in the existing code. Storing in a different system increases the chance that they will become lost to future developers. Bytes are cheap, the time it takes to recreate another developers intent is $$$.