The Best Code Documentation ‘Tool’ Ever Made (opens in new tab)

I can confirm this. Function names tend to be much more reliable than comments. Here's an example from Java that can lead to security problems. Consider setSeed from java.security.SecureRandom:

  /**
   * Reseeds this random object. The given seed supplements,rather than
   * replaces, the existing seed. Thus, repeated calls are guaranteed
   * never to reduce randomness.
   */
  synchronized public void setSeed(byte[] seed) {
    secureRandomSpi.engineSetSeed(seed);
  }

Note that the name of the method conveys something different than the comment says. From the method name, I would expect setSeed to set the seed, and not to add to the seed. A better name would have been "addSeed".

Unsurprisingly, some implementations of java.security.SecureRandom follow the comment, others follow the method name - causing a potential security issue. To complicate things further, note that the comment in the equivalent Android class java.security.SecureRandom requires setSeed to set the seed, see: http://developer.android.com/reference/java/security/SecureR...

Thus, security libraries implementating of java.security.SecureRandom cannot implement both, the Oracle and the Google version, at the same time in accordance with the specifications. This could have been avoided if the time spent on commenting setSeed would have been spent on finding a better method name.

How do you write unit tests for classes like this? A lot of reflection I assume?