Skip to main content

How Come U Don't Call Me Anymore?

Posted by editor on November 24, 2006 at 7:21 AM PST

What's the best way to make sense of an API?

For the earliest Java programmers, a handy copy of Java in a Nutshell was essential. Yet nowadays, the need to look up method signatures in a book has fallen by the wayside for a lot of people, as IDE's auto-complete method names and fill in parameters. Combined with Javadocs, this gives a lot of developers everything they need.

Or does it? How much information do you need to successfully use a given API? For example, Container.add (Component, Object) seems straightforward enough, but do it on a Swing root pane container (like a JFrame) and you get an exception (because you're supposed to add to the root pane, not the container itself). Even though the syntax is viable, the semantics aren't. This argues for some kind of documentation beyond just descriptions of methods, in favor of one that describes higher-level processes, and where the various method calls play into those processes.

Of course, some would say that's a design smell that indicates Swing itself is broken for having a seemingly sensible method call blow up in your face so badly. There are some who suggest that API's that aren't themselves self-documenting are inherently defective. You see this a lot from the Objective-C camp, where you have to name your parameters in every call, even when the possible parameter is obvious from its type (for example, if Obj-C had an equivalent to the Container.add() above, calling it might look like [myContainer add object: myComponent constraint: gridBagObject]. As you can see, this makes the purpose of the mysterious second argument explicit to every caller. More clarity, at the price of more keystrokes. So what do you think of that approach?

With this in mind, the latest Poll asks "What's your preferred form of API documentation?" Cast your vote on the front page, then visit the results page for current tallies and discussion.

In Java Today,
the second part of the SDN's introduction to JAX-WS has been posted, continuing a tutorial on how to develop web services and their clients with Java SE 6. In Introducing JAX-WS 2.0 With the Java SE 6 Platform, Part 2, you'll see how to create a client to the eBay production server, using Java SE 6 and NetBeans.

Started a project but don't know how to use the source control repository or even what it's for? partner Collabnet has posted An Introduction to Version Control on their openCollabNet site. It offers an overview of the concepts of version control, compares the lock-modify-unlock and copy-merge approaches, and offers a basic vocabulary of important version control terminology.

The Pragmatic Problem Solving blog has posted an article on Clustering - EJBs vs JMS vs POJOs with a focus on the Java EE technologies: "Scaling out a java application traditionally has not been easy. There are a number of technologies that allow you to distribute data across multiple JVMs, but most of them are cumbersome, high maintenance and do not scale linearly. Let's discuss the pain points involved in using three different approaches namely EJBs, JMS and POJOs."