verbosity, n: The excess use of words, especially using more than are needed for clarity or precision; long-windedness |
Javadoc was an attempt to combine in a single document (the source code file) two kinds of software component documentation:
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?
static Complex add(. . . )
"returns a new Complex object"?
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:
@param
two or three lines above the declaration of that parameter?
Complex
class. Note that
it still needs:
double
parameter as well as a copy constructor.
static
arithmetic operators
subtract
,
multiply
, and divide
x1.add(x2)
magnitude
(or
abs
) function (both static and method versions)
toString()
function
equals
function
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.