I ran across some old Basic code the other day that I understood absolutely perfectly. I understood everything that it was doing.
But I had no idea WHY anyone would do this or WHEN it happened or WHAT it was trying to accomplish in the big scheme of things. It was clear...but pointless.
It took me 1-2 hours to figure out the code but 2 weeks to figure out when it was used and why.
Even Jeff's comment about SquareRootApproximation misses the point. As long as you tell me it's a square root function (comment or method, don't really care), I can test it fairly easily and I care very little which method is being used because I can easily replace (with return Math.Sqrt(n) it if it's found to be wrong.
But why the HECK is Jeff rewriting Square Root anyway? Does Math.Sqrt() have a bug or something? Does one of the many easier alternatives of computing square roots not work?
I still have absolutely no idea why this was done, what to do if it has a bug in it, nothing... Everything Jeff made a huge deal about in the article is rather pointless when I come back to his code.
Huge comment block? Easily ignored with PgDn.
Comment or Method? Don't care.
Using an enum parameter to avoid a comment? You're an annoying dork, but I don't care.
Not giving the how, why and when? Major issues when it breaks.