Comment Re:Comment your damn code (Score 1) 373
The best comments I've seen have explained why a particular string hashing algorithm was used; the algorithm used is not obvious. Or rather it's so obvious that programmers tend to think "it can't be that simple!" and go off and use a different one. Which has the same sorts of weaknesses and is slower, or avoids the weaknesses at a massive performance cost in normal deployments; the comment explains that this has already been tried and warns future programmers that repeating this particular blunder isn't worth it. (And yes, I didn't believe it the first time I read it, but I was cautious enough to performance check the code against all the "industry best practice" hashing algorithms I could find; they really are slower on our typical sample data and have the same sorts of problems.)
Another great comment I saw was just a reference to the academic paper that the implemented algorithm had been cribbed from. Some algorithms in multi-precision arithmetic and image processing are sufficiently complicated to be things that properly qualify as Non-Obvious; you need to read the literature to comprehend what's going on.