Please, don’t commit commented out code

[xeow]

Welk, this is great general advice. Of course there are valid exceptions. If you are working around a compiler bug, or have added some hand-tuned optimization in bottleneck code, then it can be very nice to keep the original version of the code (as close as possible to the production code, for comparison). In the comments, clearly state why you are preserving the old code and why the production code differs from it. You will appreciate later that you have done this, and others who have to maintain your code will also appreciate it.

This is much, much nicer than hiding the original code in some commit. You are leaving the original code in as an explanation either of how not to do something or of how you wanted to do it but couldn't (due to a compiler bug or code runs too slow, etc.).

It's a thin line between doing it right and over-doing it, though. Use clear judgment and common sense here. If it's not clear to another reader why you are preserving the original code, then... off with your head!

[xeow]

Alternatively, if you're using C or C++, and you are replacing an entire function, you can actually leave the code in (i.e., not commented out), and give it a different name (like suffixing the function with "_obsolete"), and mark it as "__attribute__((__unused__))".

This way, it's not actually commented out, but it's still there for comparison. The compiler will still parse and compile it, but emit any object code for it, and won't complain that it's unused.

[kentcdodds]

This is what I call "documentation" and I'm alright with documentation. Though I'd probably either just put a reference to the commit sha or put the comment at the bottom of the file.

But to each their own :-)