BT
x Your opinion matters! Please fill in the InfoQ Survey about your reading habits!

Article: Joshua Bloch: Bumper-Sticker API Design

by Abel Avram on Sep 22, 2008 |

In this article, Joshua Bloch, Chief Java Architect at Google and former Distinguished Engineer at Sun Microsystems, presents a list of maxims intended to be a concise summary of good API design guidelines. The maxims represent the abstract written by Joshua for his session "How to Design a Good API and Why it Matters" held during JavaPolis 2006.

Read Article: Joshua Bloch: Bumper-Sticker API Design

Watch Presentation: How to Design a Good API & Why it Matters

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Documentation... by Seb Rose

"APIs should be self-documenting: It should rarely require documentation to read code written to a good API. In fact, it should rarely require documentation to write it."

"Documentation matters. No matter how good an API, it won't get used without good documentation. Document every exported API element: every class, method, field, and parameter."

A contradiction, I think.

Re: Documentation... by Kurt Christensen

There are always contradictory principles in engineering. That's why design is a non-trivial activity.

Re: Documentation... by Albert Hwang

The first refers to documentation of the code that uses the API. The second refers to the documentation of the API itself. If the API is properly named, then the code that uses it does not require documentation.

For example, if your API had a method that parsed a string and removed all white spaces, 'trim' would be much better than 'parse'.

// does not require documentation
a.trim();

// does require documentation
// parse string and remove all white spaces
a.parse();

Converting use-case tests into examples in tutorials: code citing by Peter Arrenbrecht

Maintain the code for uses-cases as the API evolves. Not only will this protect you from rude surprises, but the resulting code will become the examples for the API, the basis for tutorials and tests.


I wrote a tool to cite snippets of Java source code into documentation for exactly this purpose. Supports omitting irrelevant detail and highlighting especially relevant parts.


You can see it in action in a largish project in that project's Quick Start example and all of the tutorial, as in this example.

I've read this before. by Jasper Novotny

These things are a lot in Jaroslav Tulach's new book. Only real difference is that 'diamonds' above are 'stars' there.

Re: I've read this before. by Abel Avram

These things are a lot in Jaroslav Tulach's new book. Only real difference is that 'diamonds' above are 'stars' there.


Joshua Bloch's article is just a late follow-up of his presentation done in 2006 (www.infoq.com/presentations/effective-api-design). I hope you don't suspect Bloch plagiarizing Tulach.

Diamonds vs. stars by Jaroslav Tulach

There is a significant difference between diamonds and stars. While diamonds are said to be forever, nobody considers stars eternal. As such the allegories are not the same. They are in fact quite different. Read more...

Re: I've read this before. by Rich Unger

Whoa, I highly doubt anyone would ever suspect such a thing. Not least because Jaroslav's book is almost entirely devoted to disproving the last one: "API design is an art, not a science." He argues (convincingly, I think) that there are sound engineering principles which can be applied to design an API.

Re: I've read this before. by Ilja Preuß

Jaroslav's book is almost entirely devoted to disproving the last one: "API design is an art, not a science." He argues (convincingly, I think) that there are sound engineering principles which can be applied to design an API.


So, are you saying that engineering is science, not art? ;)

A collection of resources on API design by Christopher Bare

I've collected a set of good resources on API design here:

digitheadslabnotebook.blogspot.com/2010/07/how-...

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

10 Discuss

Educational Content

General Feedback
Bugs
Advertising
Editorial
InfoQ.com and all content copyright © 2006-2014 C4Media Inc. InfoQ.com hosted at Contegix, the best ISP we've ever worked with.
Privacy policy
BT