A standard way of producing bad documentation . . .

Javadoc® invites verbosity
© Conrad Weisert, Information Disciplines, Inc., 2 September, 2012

verbosity, n:   The excess use of words, especially using more than are needed for clarity or precision; long-windedness

Wiktionary

Javadoc was an attempt to combine in a single document (the source code file) two kinds of software component documentation:

  1. Usage documentation for people using or considering using the component.
  2. Maintenance documentation for programmers making improvements or other changes to the component.

Readers of this web site know that we believe Javadoc fails at both. We see more and more examples in textbooks, in articles, and in actual software in which the two audiences are poorly served by confusing attempts to comply with the pressure to use only Javadoc for component documentation.

Let's just consider the maintenance (type b) documentation. Here's a fragment of a positive example from a highly respected source:1


//*
  * This immutable class represents <i>complex numbers:</i>
  *
  */
public class Complex {
   /**
    * Holds the real part of this complex number.
    * @see #y
    */
  protected double x;
 
  /**
   * Holds the imaginary part of this complex number.
   * @see #x
   */
 protected double y;

  /*
  * Creates a new Complex object that represents the complex 
  * number x+yi
  * @param x the real part of the complex number.
  * @param y the imaginary part of the complex number.
  */
 public Complex(double x, double y) {
  this.x = x;
  this.y = y;
 }

  /** 
   * Adds two Complex objects and produces a third object that 
   * represents their sum.
   * @param c1 A Complex object
   * @param c2 Another Complex object
   * @return A new Complex object that represents the sum of
   *     <code>c1</code> and <code>c2</code>
   * @exception java.lang.NullPointerException
   *            if either argument is <code>null</code>.
   */
  public static Complex add(Complex c1, Complex c2) {
  .
  .
  .
} 

Doesn't that remind you of a high-school sophomore's attempt to pad an essay or an examination answer with repetitive verbiage, in order to make it look more substantial?

We won't question the other strange design choices here, since this article is just about documentation. Note that we're not singling out the author of that book for criticism. The above example is all too typical of Javadoc documentation.

Compare that with what a reasonable programmer would have coded without Javadoc:


//  Complex number class

 public class Complex {
   protected double realPart;
   protected double imagPart;

  //  Constructors
   
  public Complex(double rp, double ip) {
    realPart = rp;
    imagPart = ip;
  }

//  Arithmetic operators

 public static Complex add(Complex c2, Complex c2) { 
  .
  .
} 

Everyone would agree that the second version is far more readable from the point of view of a maintenance programmer, but some might ask whether it isn't possible to write the Javadoc version in a cleaner, less repetitive way. Perhaps, but:

The Javadoc version may then consume a dozen pages of source-code listing, while the concise, more understandable version might fit on two pages. (We don't even want to think about the HTML pages Javadoc would generate.)

So what about the usage (type a) documentation? We'll address that in a later article.


1—David Flanagan: Java in a Nutshell (Fifth Edition), 2005, O'Reilly, ISBN 978-0-596-00773-7, p. 312.

Last modified September 5, 2012

Return to technical articles
IDI home page.