When Commented-Out Code Is Acceptable

My fellow Dutch ALT.NET member Jan Van Ryswyck wrote a post about how bad commented-out code is. I also truly hate it when i see code that is commented-out. It's such a waste of time because every time i see it, i immediately start wondering "is this something that we still need to add? Does it simply not work yet? And if so, why not? Who the hell did this? Why is he wasting my time?". Putting code in comments and leaving it there is generally a sin.

However, there are two situations where i do find it acceptable. Dare i even say helpful. The first situation is when you've made a very non-obvious performance improvement to a piece of code that was proven to be slow by a profiler. In those situations, i generally leave a comment saying something like "the following block of code was originally written as follows, but was proven to be a performance bottleneck". After that i have the original code in comments, followed by a description of what turned out to be the problem. After that, i put the modified code and then i'll have another comment discussing why the new code avoids the problem. I have to admit that this generally looks ugly. However, it does tend to avoid other people looking at the modified code and thinking "hey, i can make this much simpler" and then proceeding to write a more readable version of that piece of code which might re-introduce the performance problem.

The other situation is in a TestFixture for 'Learning Tests' (couldn't find a good link to describe this concept). Learning Tests are basically tests where you can experiment with a library that you don't have too much experience with. Learning Tests can be very valuable, but they generally don't need to be run after you've learned whatever it was that you were trying to figure out. But should you throw away the code after that? It might be useful to other team members. But i don't like to put it on Ignore either because each ignored tests feels like a leftover TODO to me. So in that case, i also put the code in comments.