When Commented-Out Code Is Acceptable
Posted by Davy Brion on September 21st, 2008
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.
September 22nd, 2008 at 9:13 am
Code can be part of the documentation. To me, this is a different thing. Putting a piece of code in the documentation explaining why it doesn’t perform well is something you do because you care. You, as the code writer, want the code to make sense for the next guy.
The commented-out code that I was refering to is just the opposite of care, namely ignorance. This is the worst enemy of any software system.
Nice follow-up B.T.W.
.
September 22nd, 2008 at 10:32 pm
[...] Commented-Out Code and Broken Windows – Jan van Ryswyk ‘ To me, a piece of code that contains commented-out lines is just another piece of crap ‘ I always feel like Ive done civilization a service when I remove old commented-out code from version-controlled source, so agreed here. Davy, on the other hand, has some situations where he leaves it, though [...]
October 15th, 2008 at 1:03 am
For your second case, Nunit has an attribute called “Explicit”. It is kind of like “Ignore” but not as strong… you can still click on the test and run it… explicitly. It just doesn’t get run automatically.
What do you think of that approach?
October 15th, 2008 at 7:00 am
nice! didn’t know about that one
October 17th, 2008 at 9:51 am
Hi
I like to use XML comment for and public properties/function information.
October 17th, 2008 at 9:52 am
Sorry for using < in previous comment =)
I like to use XML comment for “example” and “exception” public properties/function information.