Over a million developers have joined DZone.

How Not to Write Java Documentation...

DZone's Guide to

How Not to Write Java Documentation...

· Java Zone ·
Free Resource

Secure your Java app or API service quickly and easily with Okta's user authentication and authorization libraries. Developer accounts are free forever. Try Okta Instead.

I've got this draft box full of unpublished blogs - mostly because they might insult somebody. This one is five years old and as apropos today as it was then.

2005-07-25 00:48:52 A java newbie posted to nbusers saying "I want to put an image into an AWT frame. What component do I use?"

Strangely, the answer is, there isn't any. It's trivial to write one:

public class ImagePanel extends Canvas {
private BufferedImage img = null;
public ImagePanel(String name) {
setImage (name);

/** Load an image from the jar, path relative to ImagePanel.class */
public void setImage (String name) throws IOException {
img = ImageIO.read(ImagePanel.class.getResourceAsStream(name));

public Dimension getPreferredSize() {
return img == null ? new Dimension() : new Dimension (img.getWidth(),

public void paint (Graphics g) {
if (img != null) {
((Graphics2D) g).drawRenderedImage(img,

Before someone cries "Ha! Gotcha! You Sun employees are dummies!", yes, there is a blazingly, stunningly non-obvious way to do this in one line of code:

new JLabel (new ImageIcon (ImagePanel.class.getResource("some_jpeg.jpg")))
No newbie is ever going to figure that out. It's compact and cute. But it doesn't count. Too non-obvious.

The thing is, I can totally imagine this guy's situation. I want to display an image. Seems simple enough - there ought to be a component for that. But there isn't any obvious candidate. Putting myself in his shoes (screen goes fuzzy as we flash back to my first days coding in Java)...

So I look at the docs for java.awt.Image. It says "The abstract class Image is the superclass of all classes that represent graphical images. The image must be obtained in a platform-specific manner." Well, that's not too useful... [not to mention wrong - or at least, misleading - ImageIO.read() is pretty platform independent, and so is Toolkit.loadImage()]. Hmm, I'll try the docs for BufferedImage, it's a subclass. Hey, that's better. It says "The BufferedImage subclass describes an Image with an accessible buffer of image data. A BufferedImage is comprised of a ColorModel and a Raster of image data." Hmm, nothing about reading or loading an image here. Where do I get one? I'll try Raster, that's its data, maybe that's where you load the data...

At this point I've gone down the rabbit hole - I'll spend at least a half hour digging through Rasters, ColorModels, ImageObservers and all sorts of other bric-a-brac that's useful if you're writing HotJava or Photoshop - when all I want to do is get my grubby little paws on an image!

There is a school of thought that says reference documentation should only describe the topic being discussed - and I disagree violently with it. This is a perfect example of why - someone is trying to do a very simple task - display an image. They have components. Fine. They have images. Fine. But nowhere in the documentation does it say either how to get an instance of an image, or how to paint one once you've got it!

I'm just amazed. The code above is very simple, but one could easily spend a day trying to figure out what to do and end up with something massively more complex. How many hours have how many people wasted over the years, starting out in Java, just trying to do this simple thing and running into this particular brick wall?

So, please, for all that's precious in the world: If you're writing javadoc for a class and it's not incredibly obvious how to get an instance of that class, describe where you get one. Describe the basic steps of how to use it. Especially if the thing someone does with it is not expressed in methods on it. If a documentation style maven says your docs are cluttered, tell them I told you they should be cluttered. If someone very clever comes along and says (ominous soundtrack), "Ah, but you're going to have to maintain that documentation. You say, okay, I'll maintain it. And if your documentation maven then says, "What if one day your example is WRONG!!!" pat him on the head, tell him he's very clever (that's all he wants anyway) - and send him on his way.

Reference documentation may be intended to be "reference" documentation - i.e. it talks about the thing the documentation refers to. That doesn't mean it should talk about nothing else, like how to use the thing being referred to.

From http://weblogs.java.net/blog/timboudreau/

Secure your Java app or API service quickly and easily with Okta's user authentication and authorization libraries. Developer accounts are free forever. Try Okta Instead.


Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}