The problems with HTML

The ongoing success of Java is closely related to the availability of the HTML documentation generated with the JavaDoc tool. However HTML has some inherent issues: It is only possible to browse one class at a time. Relationships between classes are only textual. The documentation of classes can become very inconvenient to use. For example the documentation for java.awt.Component is 80 pages long. Following a link loses the current context. There are some attempts to include diagrams in the documentation, but these are rare, inconsistent and visually not very attractive. Class diagrams could mitigate some of these issues, however there are some points which need to be addressed first.

The problems with UML

When I was in 4.th grade a children book by Boy Lornsen was quite popular in my class. "Robbi, Tobbi und das Fliewatüüt" tells about the adventures of child inventor Tobias Findteisen (Tobbi), his friend the roboter ROB 344-66/IIIa (Robbi) with the Fliewatüüt. The Fliewatüüt is a all-in-one vehicle which is able to fly (Flie-gen in german), to swim in water (Wa), and to drive as a car (making the sound Tüüt with the car horn). The book was eventually made in a german television series available on YouTube. As kid I found the idea of a Fliewatüüt fascinating and wanted to invent one later in my life. The adults however, were quick to point out, that a Fliewatüüt wouldn't be such a good idea. It would never be a good car or a good boat or a good aircraft. Whenever moving around, 66% of the weight will be nothing but be an encumbrance. This may be tolerable if all modes of transportation are used regularly. However if you are mainly driving around, a dedicated car is much better.

UML is like a Fliewatüüt

The Unified Modeling Language (UML) was made for all phases of development and is furthermore platform neutral and language neutral. However nowadays the number of developers which only use the standard libraries is much much higher than the number of authors of said libraries. Methods and procedures which accommodate authors or different platforms impede the work of users who must continuously query the documentation. Also while there are many tools to generate UML diagrams, UML is designed for pen and paper. This restriction precludes a lot of the capabilities of a computer.

Other problems of current class diagrams with real world circumstances are demonstrated in Figure 1. (Clicking on the image opens a new window with the diagram in full size.)

The diagram shows just 15 classes from the collection framework of an older version of the JDK. However note how difficult it is to follow lines. Using the diagram is very inconvenient. Scrolling is unavoidable, and a printout results in 12 pages. For an added bonus try to find the differences between the first two constructors of LinkedHashSet.

What can be done better?

Design Principles

To improve class diagrams, the following design principles are postulated:

• Design infrastructure for write once, read forever.
• Rely on areas, colors, textures and font styles instead of lines.
• Use the elements of the design: contrast, alignment, repetition and neighborhood.
• Be as near to Java conventions as possible.
• Keep context visible. Scrolling should be avoided. All relevant information should be on one page.
• Organize and compress information, hide redundant information.
• Use progressive disclosure to add information dynamically.
• All information available with JavaDoc should be reachable.

In the next page it will be explained how this requirements have been implemented on this site.