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

Related Editorial

Speed Matters: See why Nike, Groupon, and Comcast are using New Relic

Extend Your Java EE Apps with a Mobile Web Interface

Beyond HTML5 and Native Development: Build Richer, More Functional Mobile Applications

Why NoSQL - Three Trends Disrupting the Database Status Quo

Infographic: Just How Big is the Nerd Economy

Related Sponsor

Get code level visibility into your web apps. All for free.

Try New Relic Today.

Hello stranger!

You need to Register an InfoQ account or 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

Community comments

Documentation... by Seb Rose Posted

Re: Documentation... by Kurt Christensen Posted

Re: Documentation... by Albert Hwang Posted

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

I've read this before. by Jasper Novotny Posted

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

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

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

Diamonds vs. stars by Jaroslav Tulach Posted

A collection of resources on API design by Christopher Bare Posted

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-...