Java Doc Breaks Once And Only Once

The main complaint against JavaDoc is that it goes against SelfDocumentingCode. Also it encourages MassiveFunctionHeaders.

(Taken from MassiveFunctionHeaders):

JavaDoc comments breaks OnceAndOnlyOnce. Have you ever seen nonsense like this?

  /** Extract the address from the message.
  @param message The message
  @return The address */

  String extractAddressFromMessage (Message message)

Noise. Lots of noise.

I've always found that you need to play that game with javadoc, because your documentation output ends up looking ugly if you don't state the obvious. I'm guilty of writing horribly redundant stuff like that in classes that I expect to be very user-visible. -- LukeGorrie

It gets worse. See this example taken from JavaDoc:

   /**
    * Display an exception in a relatively user-friendly dialog box.
    * The user can display a traceback by pressing a button.
    *
    * @param owner Owner of the dialog box, or null for a top-level
    * dialog.
    * @param cause The exception that caused the problem. May not be
    * null.
    * @param title Title for the dialog box, or null for a default
    * title.
    * @param msg A user-friendly explanation of the problem, or null
    * for no explanation.
    * @param options Bitmask of option buttons to display
    *
    * @return An option value, or zero if the window was closed
    * with no option selected.
    * */ 

static public long showException(Frame owner,
Throwable cause,
String msg,
String title,
long options)
{
//....
}

-- GuillermoSchwarz

And what's wrong with that? You know from the method certain things can be null or what will be down with them? In the extractAddressFromMessage case, I just don't write the extra doc. -- AnonymousDonor

Nobody forces you to write doc comments like that. I usually just leave out the information that's obvious from the method signature. Yes, it makes the generated pages look very sparse, but they're just as helpful (sometimes more so) for a programmer trying to use the library in question. Sometimes, just having the JavaDoc output with no comments is helpful, as it quickly lets you view the interface and browse through the available methods.

I'd ReFactor the above JavaDoc comment into:

   /**
    * Display an exception in a relatively user-friendly dialog box.
    * The user can display a traceback by pressing a button.
    *
    * @param owner Null for a top-level dialog.
    * @param cause May not be null.
    * @param title Null for a default title.
    * @param msg A user-friendly explanation of the problem, or null
    * for no explanation.
    * @param options Bitmask of option buttons to display
    *
    * @return An option value, or zero if the window was closed
    * with no option selected.
    */

Then the next step is to refactor the code and see if even that can be eliminated. Msg could be renamed to "explanation", eliminating the need for a comment to it, and there's NullConsideredHarmful. Then the method name might be renamed to indicate what it returns. Using a BitVector? instead of a long documents the options bitmask, at some performance penalty (but this is GUI code, performance shouldn't really matter). -- JonathanTang

Why document that parameters can't be null? Instead of simply documenting that parameters can't be null, you should throw meaningful exceptions which should be handled at appropriate places. This means that client code will break at compile time, not at run time. This is a GoodThing. -- GuillermoSchwarz No! No! Bad!!! This would force the user to explicitly handle a condition that would never happen. Assuming this method would be called from a catch block, there is no way the caught exception would be null. You're merely wasting 4 lines of code (and thoroughly annoying the programmer) for each and every use of the method. -- alf'

Example:

   /**
    * Display an exception in a relatively user-friendly dialog box.
    * The user can display a traceback by pressing a button.
    *
    * @return An option value, or zero if the window was closed
    * with no option selected.
    **/ 


static public long showException(Frame owner,
Throwable cause,
String problemMsg,
String dialogBoxTitle,
long optionsBitmaskFOrButtonsToDisplay)
        throws NoCauseException?
{
//....
}

Code is dynamic in nature. WriteOnly? code like the one typically written in C is not a GoodThing. Changing a JavaDoc comment will surely not tell anyone that the change breaks the clients. Using UnitTests is very important in those cases. UnitTests should allow the original library to fail, before clients are broken. This means clients should never use something for which an appropriate UnitTest doesn't exist.
JavaDoc is only useful when no source code is available and when no UnitTests are available. If JavaDoc is needed, most JavaDoc should be gathered from the method signature.

I think [JavaDoc] is actually a good thing if you need to publish developer documentation for a widely used API. Unfortunately, many people abuse this type of stuff for documentation heavy methodologies. At least the documentation is closer to the source. But, even with developer documentation, less is more.

I would rather say less is better.

If the parameters are more obviously named some of the need for this type of stuff should decrease. For example, there's no need to state that the Message parameter is indeed a message. Yes, it's a clear violation of OnceAndOnlyOnce. Furthermore, if the message parameter were something other than a message, don't document that either. Rename it (See BadVariableNames). Cheers, -- JasonNocks

I think that putting documentation in source code is a terrible thing. Developers can get most of what they want from the sourcecode itself (especially with well-written code) and the things they can't get are NEVER in the comments, whether Javadoc or otherwise. Meanwhile, genuinely useful technical documentation is almost always better created by technical writers - NOT developers. Javadoc is technical documentation, and in my opinion, should be created by professional technical writers using tools designed for technical documentation. As a related note, changes to embedded Javadoc often confuse source code control systems, because such systems can't or don't distinguish javadoc changes from code changes. All in all, this kind of embedded doc is a terrible idea.

A better approach is to embed, in the source code, comments that expand to references (such as URLS) to companion documentation. This documentation should have corresponding references back into the source code. This lets the documentation be created and maintained by technical writers using appropriate tools.

* Javadoc supports links to external documentation.

Even more importantly, it allows the documentation to be customizable to the audience of the documentation. The same fragment of code can have several different documentation "webs" associated with it, each web targeted at a specific audience.

JavaDoc is perhaps a poor choice for architectural documentation, tutorials, or lengthy descriptions of technical details, but it is a simple, convenient way to generate and maintain API reference docs in a way that encourages developers to keep them synchronised with the source code. Maintaining separate companion docs for API information - i.e., brief descriptions of method purposes, parameters, caveats, bugs, usage information, and so forth that normally should be documented in the code - is awkward.

And what about projects that do not have the funding or justification to pay a technical writer, or packages where the code is under development and subject to frequent changes? JavaDoc may not be perfect, but for the job it's meant to do, I'm not aware of any alternative that has the same benefits without introducing unacceptable problems. -- DaveVoorhis

A programmer can surely write whatever documentation he or she wants in a companion file linked to the source code, if no technical writer is available. It is code "under development and subject to frequent changes" for which this sort of comment is completely useless -- no developer has time to both work on the code and also update the documentation. I think it's better to have no comments at all than to have stale text that has long since fallen behind the code it allegedly describes. Meanwhile, when somebody or other DOES start to catch up, putting the documentation in the source code begins to trigger useless builds - does ANT or any other build system understand how to NOT trigger builds based on purely documentation changes? I don't think so.

Embedding API reference information in source code - for sharing with the rest of the development team - is something I've been using to useful effect for the past twenty years in everything from JCL and TSO CLISTs, to 80x86 assembly language, to SAS and ExBase, to C, C++, PHP and Java. It is a technique that works, and it works well. There is nothing more convenient than putting key information - warnings, brief summaries of purpose, pitfalls, limitations, and so forth - immediately above each method or function where your colleagues will see it when they're making use of your classes, methods, and routines. It is a potent tool in the development communication chain, and far more effective than maintaining separate documents - which are awkwardly distant from the code they refer to and inevitably get neglected and out of sync with the code - or, obviously, not documenting at all. Changing a source file merely to update documentation is rare; one soon gets into an easy habit of making a change to a function or method and immediately making corresponding changes to the relevant docs above it. Obviously, this causes no extra builds. Occasionally, source documentation does get changed on its own, and indeed this triggers a build, but the cost of that is negligible compared to the value of having handy documentation in the source code where you need it most. JavaDoc adds value to the practice of embedding useful information in the source by enforcing consistency, and by automatically generating Web pages which frequently save having to plow through the source code when looking for information about the API. -- DaveVoorhis

Sorry, Dave. My experience differs from yours. For example, when you write "There is nothing more convenient than putting key information - warnings, brief summaries of purpose, pitfalls, limitations, and so forth - immediately above each method or function where your colleagues will see it when they're making use of your classes, methods, and routines", you recall memories of countless projects where my teams and I have had to pore through and ultimately ignore paragraph after paragraph of obsolete random junk -- tidbits that were no doubt insightful and important in April of 1993 and were completely useless by July of that year, and that still remain in the "code". Such stuff is yesterday's news. My teams have found that, for example, companion wikis are far more helpful than embedded blocks of javadoc. The comments you describe are NOT code. They aren't source code, and they aren't documentation. Helpful, yes of course, but helpful in the way that yellow post-its are helpful. My own experience with "automatically generated" documentation is that "plowing through the source code" is the only reliable way to gain information about the API for anything that isn't literally generated automatically from the source code.

Excuse me for given vent to a spleen, but you're simply demonstrating that you and your teams are pathologically undisciplined. If you are generating "paragraph after paragraph of obsolete random junk," and more importantly, are maintaining "obsolete random junk" anywhere, then something has gone horribly wrong with your development process. "Obsolete random junk" is "obsolete random junk" no matter where you maintain it. How, exactly, are "companion wikis" - which presumably contain useful API documentation - more convenient or inherently more up-to-date than maintaining exactly the same text a mere cursor movement or two above the function or method declaration? Furthermore, see EricHodges's comment below, which aside from anything else, is a valuable reason for maintaining JavaDoc documentation. Not only that, but if you're going through the laborious and slow process of reading someone else's source code in order to divine information that could simply be read from a snippet of documentation, then you're burning your client's money in a manner that is nigh unto fraudulent. -- DaveVoorhis

: You're excused. DaveVoorhis asks "How, exactly, are "companion wikis" - which presumably contain useful API documentation - more convenient or inherently more up-to-date than maintaining exactly the same text a mere cursor movement or two above the function or method declaration?" Companion wikis, a companion free-text, or - perish the thought - even an MSWord document are, in my experience, more convenient because they use tools optimized for editing text, as opposed to source code. No "/**", " *", or "**/" characters are necessary at linebreaks. Editors have had variable-width windows and proportional fonts for more than twenty years, yet the javadoc documentation standard embeds an implicit assumption about both the width of the window (because of the line decorators) along with an assumption of a mono-spaced font. Applying these constraints to source code is, in my opinion, dubious at best. Requiring them of documentation strikes me as indefensibly archaic.
: David argues that his teams are disciplined enough to keep the embedded documentation synchronized with the evolving source code. It seems to me that a team disciplined enough to accomplish this is surely capable of using a different editor window to enter their documentation. A source code management approach that can handle source files, libraries, include files, and makefiles can surely also handle documentation files.
: I am not (here anyway) arguing against documenting the elements that javadoc attempts to address. I am suggesting that the approach embodied by javadoc mitigates against, rather than in favor of, such documentation. If we accept the existence of multiple fonts, multiple windows, hypermedia, a rich variety of editing tools, source-code control systems, and all the other components of software development in the twenty-first century, then why should we impose the outmoded constraints of javadoc on our documentation? I'm not trying to be cantankerous, I'm asking a genuine question. If we each agree that meta-information about the code needs to be conveyed to a variety of audiences, surely we can discuss various techniques for accomplishing that - a discussion that will inevitably include a description of the shortcomings of current approaches and how they might be avoided.

I accuse all parties involved in this argument of making good points, but by being heated, of getting carried away and not seeing the flip side to each argument.

I suggest that there is a germ of truth to be gleaned from each party's position, even when the two positions are largely opposed.

I further suggest that y'all explore points of agreement first, skip the moral judgements and name-calling, and find a middle position where no-one is evil, and then state your personal preferences (there is no absolute truth on these things) that go beyond/are opposed to that middle position.

For instance: it is an infamously well-known problem that documentation and code tend to get out of sync. That much is simply objective, IMHO. What to do about that becomes a judgement call, and a matter of differing experiences, and a matter of taste, sometimes, even if we feel that it is objective, not subjective.

If you think that there is an objective statement to be made, by all means, do so. Otherwise, there actually is room in the world for radically different styles that each may work - unless one wishes to declare oneself close-minded, which surely is not the case here? -- DougMerritt

Three things: 1. I vow never to click on a JavaDocBreaksOnceAndOnlyOnce link ever again; 2. I shamefully admit to being the most closed-minded person I know; 3. DougMerritt is right, and thanks to him for stopping this from turning into a mutual curbstomping of prodigious scale. -- DaveVoorhis

: I wonder if an rdf-style content markup might help address these concerns. Building on the LiterateProgramming ideas of DonaldKnuth, what if "source code" was a knowledge base, maintained using tools optimized to support it, that was traversed by compilers and similar tools when necessary? It seems to me that we're close to that already, with Subversion and even EnvyDeveloper. In the current world, code fragments and unit tests come from all over the world. Isn't this the kind of problem that RDF and the SemanticWeb was intended to address?

Javadoc lets tools like Eclipse provide context sensitive help for every class that has source code. That alone is worth the minimal cost of maintenance. -- EricHodges

Actually, you need to distinguish between published and non-published code. With published code, such as the JDK classes, most programmers read the JavaDoc and ignore the source code, making the JavaDoc quite valuable. With non-published code, such as enterprise applications, programmers using the code will be reading the source code, and JavaDocBreaksOnceAndOnlyOnce.

What about attaching JavaDoc to interfaces but not classes? Is there a win to be had there?

repeated interest at end of JulyZeroFive

JavaDoc contains some information that are not immediately readable from the method signature -- for example, if a method just takes (string, string, string) that's hardly useful without some comment, and it has a deprecation feature which is great when you RefactorGently?. The problem is that it does contain information that is immediately readable from the method signature or the source; and programs that generate ApiDocumentation? would do better to rely on this instead of on a flimsy comment. Suggestion for designers of future languages and source documentation systems: allow comments for extra information, but avoid redundancy please. CategoryDocumentation