BT

Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ
News Articles Presentations Podcasts Guides

Topics

Choose your language

InfoQ Live September

See what’s next in Large Language Model (LLM) architectures used in tools like ChatGPT.
QCon San Francisco

Learn what's next in software from world-class leaders pushing the boundaries. Attend in-person or get video-only pass to recordings.
QCon London

Discover new ideas and insights from senior practitioners driving change in software. Attend in-person.
The Software Architects' Newsletter

Your monthly guide to all the topics, technologies and techniques that every professional needs to know about. Subscribe for free.

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

Article: Joshua Bloch: Bumper-Sticker API Design

Bookmarks

Sep 22, 2008 less than one minute

Write for InfoQ

Join a community of experts. Increase your visibility.
Grow your career.Learn more

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

This content is in the Microsoft topic

Related Topics:

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.

    Back to top
  • 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.

    Back to top
  • 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();

    Back to top
  • 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.

    Back to top
  • 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.

    Back to top
  • 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.

    Back to top
  • 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...

    Back to top
  • 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.

    Back to top
  • 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? ;)

    Back to top
  • 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-...

    Back to top

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