BT

InfoQ Homepage News Article: Joshua Bloch: Bumper-Sticker API Design

Article: Joshua Bloch: Bumper-Sticker API Design

Bookmarks

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

Rate this Article

Adoption
Style

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.

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

Community comments

  • Documentation...

    by Seb Rose /

    Your message is awaiting moderation. Thank you for participating in the discussion.

    "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 /

    Your message is awaiting moderation. Thank you for participating in the discussion.

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

  • Re: Documentation...

    by Albert Hwang /

    Your message is awaiting moderation. Thank you for participating in the discussion.

    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 /

    Your message is awaiting moderation. Thank you for participating in the discussion.

    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 /

    Your message is awaiting moderation. Thank you for participating in the discussion.

    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 /

    Your message is awaiting moderation. Thank you for participating in the discussion.

    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 /

    Your message is awaiting moderation. Thank you for participating in the discussion.

    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 /

    Your message is awaiting moderation. Thank you for participating in the discussion.

    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ß /

    Your message is awaiting moderation. Thank you for participating in the discussion.

    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 /

    Your message is awaiting moderation. Thank you for participating in the discussion.

    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

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

BT

Is your profile up-to-date? Please take a moment to review and update.

Note: If updating/changing your email, a validation request will be sent

Company name:
Company role:
Company size:
Country/Zone:
State/Province/Region:
You will be sent an email to validate the new email address. This pop-up will close itself in a few moments.