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:

• Very soon this documentation becomes outdated, because some other developer will come and change the code, but forget to change the documentation. It may even be the same developer, because while he was standing in line for coffee, it occurred to him that he forgot to process one rare case. When he comes back, he adds the desired IF into the code, but forgets that he already has javadoc, which needs to be maintained.
• This documentation does not describe the mass of cases: how the method behaves, if the input comes null or empty string? What if address contains house number, but misses apartment number (ie bourgeois took home a whole)? What’s that empty parameter between the EE and Tallinn?
• Documentation doesn’t describe what this method returns.
• There are three extra lines in the documentation: “*, “@ param flatAddress” and “@ return Formatted address”. Just think: they occupy a large part of the documentation, and they are absolutely useless!

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 ….

• Pass # 1: Transform the main comment Format string as address to a method name: toString -> formatAddress.

• Pass #2: Transform parameter description expected input, expected: ... from comment to a unit-test.

• Pass #3 (my favorite): (мой любимый) All other comment text - wipe fuckin! Do not spare him, it was born in vain! This is coding sparta!

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?

• It’s just shorter: there are now 4 rows compared to former 8.
• This test will never becomes obsolete, because it will run automatically every time you build the project, and if the programmer change the code, and forget about the method, it immediately pops up.
• You can describe all the rare cases: the empty string, missing keys, invalid values, etc.

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.