The Artima Developer Community
Interviews | Discuss | Print | Email | First Page | Previous | Next
Sponsored Link

Analyze this!
A Conversation with James Gosling, Part I
by Bill Venners
Jun 9, 2003

<<  Page 3 of 3


Visualizing with JavaDoc

Bill Venners: What I mostly use for visualization is JavaDoc, because it's an abstract view of the public interface. I generate JavaDoc a lot as I'm designing and developing. I look at the HTML pages generated by JavaDoc and think, well, this looks kind of confusing. And I go back and make some changes to the code. I may not be able to see that it is confusing just by looking at the code. So I think having different ways to visualize code and designs as it is being developed can help guide the design.

James Gosling: Jackpot's editor component tries essentially to do what amounts to real time JavaDoc. JavaDoc is a funny thing. When I did the original JavaDoc in the original compiler, even the people close around me pretty soundly criticized it. And it was interesting, because the usual criticism was: a good tech writer could do a lot better job than the JavaDoc does. And the answer is, well, yeah, but how many APIs are actually documented by good tech writers? And how many of them actually update their documentation often enough to be useful?

Bill Venners: For me JavaDoc doesn't just serve as a way to document the design, it serves as a way to visualize the design. If I see huge classes with 300 public methods, or dozens of packages with only few classes in each, I know there's a problem. It's more obvious when you're looking at the JavaDoc than at the source.

James Gosling: Right. JavaDoc has been enormously successful and enormously powerful. It's really been quite wonderful. And it's also been interesting to see the way that professional tech writers have taken to JavaDoc. A lot of the early criticism from them were things like formatting. That's largely been solved by the sophisticated doclets that people have been able to write. But the tech writers seem to now spend a lot more time just documenting the semantics of what's going on, and a lot less time fussing with structure and formatting. And it actually feels like tech writers end up being more productive.

Bill Venners: So the tech writers are in there changing the code also, and checking in their changes?

James Gosling: Yeah. That's certainly what happens around here. The tech writers are intimately involved in the engineering. And actually I've always found that to be a really good thing to do. One of my general design principles is that it's really helpful to have a good tech writer on the engineering team early on. If you're building something and you have a tech writer trying to document it, and the tech writer walks into your office and says, "I don't know how to describe this," it means one of two things. Either you've got a really stupid tech writer who you should fire. Or much more likely, you've got a bad piece of design and you ought to rethink it. You have to rethink, because an API that isn't comprehensible isn't usable.

Bill Venners: So the tech writer is giving you feedback on your design. One of the values of design reviews is that programmers give you feedback, and that's useful if it's an API because the users of APIs are programmers.

James Gosling: The problem with programmers as reviewers, and especially programmers that have been involved in the program for a while, is that they are kind of oblivious to the complexity. And lots of engineers are complexity junkies. Complexity is in many ways just evil. Complexity makes things harder to understand, harder to build, harder to debug, harder to evolve, harder to just about everything. And yet complexity is often much easier than simplicity. There's that really famous Blaise Pascal letter, where he starts, "I apologize for this long letter. I didn't have the time to make it any shorter." And that's really true.

Bill Venners: I always think the designer's job is not only to create something that will work correctly and efficiently, but something that is also easy for the client to understand and use.

James Gosling: Yeah, you've always got a customer on the other side, whether that's some high end engineer, or some chemist in the lab who's writing a piece of code. Often you've got people whose real job is something other than software, and software is their tool. They don't necessarily get off on all of the complexity. Making things simple can be a real challenge.

Next Week

Come back Monday, June 16 for Part II of a conversation with Elliotte Rusty Harold. I am now staggering the publication of several interviews at once, to give the reader variety. The next installment of this interview with James Gosling will appear in the near future. If you'd like to receive a brief weekly email announcing new articles at, please subscribe to the Artima Newsletter.

Talk Back!

Have an opinion about refactoring tools, program visualization, or JavaDoc? Discuss this article in the News & Ideas Forum topic, Analyze this!.


James Gosling's Home Page:

Bill Venners has interviewed James Gosling each year for the past five years. The four previous interviews are:

James Gosling discusses semantic models, mobile behavior, abstraction versus vagueness, testing, and repetitive stress injury. (February 2002):

James Gosling speaks on inheritance and composition, JSPs and Servlets, community design processes, and more. (May 2001):

James Gosling discusses developer tools, the realtime JVM, mobile objects, strict interfaces, and more. (May 2000):

James Gosling speaks on interfaces and protocols, servers and services, Jini, Java in the enterprise, and more. (May 1999):

<<  Page 3 of 3

Interviews | Discuss | Print | Email | First Page | Previous | Next

Sponsored Links

Copyright © 1996-2018 Artima, Inc. All Rights Reserved. - Privacy Policy - Terms of Use