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

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 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

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 4

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.