In this post, I'll discuss how javadoc is used in enterprises today. It leads to have some doubts as to the usefulness of javadoc.

Let’s start off with something not that deep, not that new and not that sexy. In fact, it’s very old and very boring – javadoc. It’s been with us since… forever… and it’s one of those things you don’t question anymore. Javadoc is standard and widely used in the java universe yet I often find myself wondering how much value it really adds to the understanding and usage of code.

Don’t get me wrong - I have nothing against the tool per se and think it’s great for documenting APIs of published libraries. But when we start looking at how it’s being used internally by software development shops, you kinda start wondering about things.

Working as a technical leader, I often find myself reviewing other people’s code. I often come across three different kinds of coder personas. I took the liberty of describing them for your entertainment pleasure. (Disclaimer: Any resemblance to persons living or dead is purely intentional - and you know who you are!)

Javadocus absentis (‘ja-və-dä-kəs ab-sənt-əs): A distant cousin of the coding cowboy, this person just doesn’t use javadoc at all. He doesn’t have time for it, didn't get the memo about javadoc being mandatory, or wrote the code before javadoc and computers existed. This person will resist javadoc until the bitter end yet is the first to complain that there isn't enough documentation around. If you force his hand, he will suddenly morph into javadocus minimus (see next paragraph).

Javadocus minimus (‘ja-və-dä-kəs ‘mi-nə-məs): Being a descendant of Javadocus absentis, this person understands that while he hates writing javadoc, resistance is futile. So he's adopted an anti-javadoc force field. You know you're in the presence of the great Javadocus minimus when you see this:

/**
 * Executes.
 *
 * @param string a string
 * @param boolean a boolean
 * @return a int
 */
public int execute(String string, boolean boolean);

Gee... thanks! Now I understand what this method does.

Another powerful weapon in the Javadocus minimus toolkit is {@inheritdoc}. Once the interface is defined, he is a few keystrokes away from this:

/**
 * {@inheritDoc}
 */
public int execute(String string, boolean boolean)
{
  return 0;
}

But wait... this only works for interface implementation or overridden methods. What about standalone classes that don't inherit code? Javadocus minimus turns to the java editor for help. Fortunately, all modern editors do this automatically:

/**
 * @param string
 * @return
 */
public boolean isJavadocusMinimus(String string)
{
  return true;
}

Javadocus minimus never creates any valuable javadoc. His code only ends up taking more space on the source control's storage. But he can continue to thrive without reprimand.

Javadocus verbosis diarrhoea (‘ja-və-dä-kəs (ˌ)vər-ˈbōs-əs dī-ə-ˈrē-ə): As a completely unrelated species to Javadocus absentis or Javadocus minimus, this person likes to document his life story in the javadoc. He loves to state the obvious and his javadoc looks something like this:

/**
  * This method returns the square root of any number. It is an improvement over the
  * standard square root method in Math.sqrt(). In mathematics, a square root (√) of
  * a number x is a number r such that r2 = x, or in words, a number r whose
  * square (the result of multiplying the number by itself) is x. Every non-negative
  * real number x has a unique non-negative square root, called the principal square
  * root and denoted with a radical symbol as √x. For example, the principal square
  * root of 9 is 3, denoted √9 = 3, because 32 = 3 × 3 = 9. If otherwise
  * unqualified, "the square root" of a number refers to the principal square root:
  * the square root of 2 is approximately 1.4142. Square roots often arise when
  * solving quadratic equations, or equations of the form ax2 + bx + c = 0, due to
  * the variable x being squared. Every positive number x has two square roots. One
  * of them is √x, which is positive, and the other −√x, which is negative.
  * Together, these two roots are denoted ±√x. Square roots of negative numbers can
  * be discussed within the framework of complex numbers. Square roots of objects
  * other than numbers can also be defined. Square roots of integers that are not
  * perfect squares are always irrational numbers: numbers not expressible as a
  * ratio of two integers. For example, √2 cannot be written exactly as m/n, where n
  * and m are integers. Nonetheless, it is exactly the length of the diagonal of a
  * square with side length 1. This has been known since ancient times, with the
  * discovery that √2 is irrational attributed to Hipparchus, a disciple of
  * Pythagoras. (See square root of 2 for proofs of the irrationality of this
  * number.)
  * @param number Any number that you want to find the square root of.
  * return The square root of the number given.
  */
public double getSquareRoot(int number);

Yeah... thanks for the math lesson!

Finally, we have convinced someone of the merits of documentation. Except that nobody will ever read it because it is too long. Worst, nobody will ever update it should the implementation of get square root change. (Hey, you never know!)

I often find myself conflicted with javadoc. I am an admitted javadocus conformitus (‘ja-və-dä-kəsˈkən-ˈform-it-əs) because I co-wrote our coding guidelines and have to lead by example. However, I try to write concise and meaningful comments and only make it more verbose for complex code. But to tell you the truth, I rarely rely on my own javadoc to understand code I’ve written a long time ago. Instead, I rely on the code itself as documentation. In the end, isn’t that the only documentation you can really trust?