Why the devil invented javadoc?

It is believed that a good program should be well documented.

SUN company even creared a special format javadoc - “a standard for documenting classes Java”. In fact, it was quite a common case in my experience, when a code did not pass Code Review just because some of its methods lacked comments.

Today I’ll tell you why the comments are evil.

Start from example

Consider the real example from live code. This is a real code written quite diligent programmer who was not lazy and wrote a commentary on his method. Pleased with himself, he went to pour himself a cup of coffee from the machine. While he is going to the office kitchen, let’s take a look at what we have here.

public class AddressUtil {
   /**
    * Format string as address, expected input
    * format:"EE ; ;Tallinn;Narva mnt;120B;831;10127"
    *
    * @param flatAddress
    * @return Formatted address
    */
   public static String toString(String flatAddress) {......}
}

Excellent! We have a correctly designed a format javadoc, from which a special program can generate HTML-documentation. As it is easy to see that (theoretically) makes this method.

Where is the hidden devil?

But where are those little things that hid the devil? And here they are:

It can be summarized in two words: » Comments lies!

That’s all. You cannot do anything with this, except the cases when you have a special position for people how review all the documentation periodically. Damn, do you really want to do that?

The magic

Now let’s do a focus-pocus and create The Magic. We make a few magical passes. Sim salyabim, Ahalan-mahalay, Lyaska-masyaski ….

What we have in the end?

public class AddressUtil {
  public static String formatAddress(String flatAddress) {......}
}

public class AddressUtilTest {
  @Test public void testFormatAddress() {
    assertEquals("Narva mnt 120B-831  10127 Tallinn", 
      AddressUtil.formatAddress("EE ; ;Tallinn;Narva mnt;120B;831;10127"));
  }
}

What the new version better than the old?

In short,

GOOD TITLE + TESTS = DOCUMENTATION

rather, executable documentation, or documentation that can not only read but also “run”, automatically checking that it is still adequate.

It is said that Confucius was a poster over the bed:

Convert comments to executable documentation

Afterword

I’m just afraid that our brave programmer, returning from the kitchen, will not understand the focus, because he had not seen our magical movements. He will get mad only because SOMEONE Nagle has deleted his comments, and he will try to find us and kill for such subversive activities.

… And his coffee gets cool in the meantime. Well, no so bad: after all, coffee, they say, is harmful. So, we did today did one good thing.

Confucius