Neuroning

I wrote about API design guidelines before, collecting links, resources, papers and hoping someone would write a book on the subject.

The wait is over! Jaroslav Toulash published a book on Practical API Design!

Take a look at the book’s accompanying website for more details.

I’m waiting for my copy.

Update: Good news! Jaroslav Toulash emailed me that he published a book on Practical API Design !!!

---

Looks like Brian McAllister may be preparing a talk on Designing Elegant APIs.

I've been very interested in good API design for a long time. But I could never find a single book on the subject. Many design and programming books provide good advice and guidelines that are essential for designing good APIs, but none of them tackles the matter directly.

I reviewed "Interface Oriented Programming" a few months back with disappointment. It may not be a bad book, but I felt it was quite basic and superficial. May be my expectations were too high, and too focused on API design.

Over time, I collected some links on the subject and shared some with Brian:

• Best Practices in Javascript Library Design (via John Resig on JavaScript API Design) - A good presentation given by the author of JQuery.

• API: Design Matters - Article by Michi Henning, ZeroC, for ACM Queue magazine.

• How to Design a Good API and Why it Matters - Excellent deck from Joshua Bloch. There's also a video of his presentation at JavaPolis 2005.

• Interface Design, Best Practices in Object-Oriented API Design in Java, by Bill Venners - This one is a Book in progress!. Unfortunately, the last updates seem to be from 2002 or so. I'm not sure if the project is still alive. Anyway, it contains many good articles.

• How To Design a (module) API - A great page on good design practices for writing APIs. It's tailored for NetBeans module writers, but is still pretty general and gives very valuable guidelines.

• How to Write APIs That Will Stand the Test of Time - A session I attended at JavaOne 2006. Presented by Tim Boudreau and Jaroslav Tulach, members of the NetBeans team. It focuses on API evolution and compatibility, but also covers usability and other guidelines. I guess they are the main guys behind NetBeans' How To Design a (module) API page linked above.

  I had the chance to speak with Jaroslav after his session and suggested he should write a book on this topic. I emailed him the references I had, and he said he would try to draft something by the end of year.

• API Usability - Focused on making APIs easy to use. The article applies general usability principles (commonly used in GUI design) to the design of APIs.

• Measuring API Usability - An interesting article by a usability engineer at Microsoft, published on Dr. Dobb's. It favors the use of scenario-based design to achieve usable APIs, and explains the use of their "cognitive dimensions" framework for measuring API usability. He also blogs about API usability.

• Krzysztof's Laws of API Design - From another Microsoft blogger on API design.

• Java API Design Guidelines - A good article from a developer who was also surprised by the lack of a book about API design. He collected some advice and additional links.

• XOM Design Principles - Some design "principles" followed by XOM (an XML parsing library).

• The Most Important Design Guideline? - A short article by C++ guru Scott Meyers.

• Humane Interface, Minimal Interface, Designed Inheritance, DSL Boundary, Duck Interface, Fluent Interface, Public vs. Published Interfaces - Some of the many great writings from Martin Fowler. These selection is on specific topics that are relevant to API design. Most of them are quite recent.

• Programmers are People, Too - An article by Ken Arnold for ACM Queue magazine: "Programming language and API designers can learn a lot from the field of human-factors design."

So, let's hope Brian gives his talk at a big conference, signs a contract with a big publisher and fills the void.

If you work as a software developer for a living, I recommend you get a copy of “My Job Went to India”. Ignore the curious title and funny cover. It’s about planning your career and making yourself a more valuable developer.

I read it right after “The World is Flat” (by the way, a fascinating description of today’s globalized economics), and it was a good 1-2 punch.

Full of great advice. Stimulating and motivating little book. It helped me find the energy to go back to work after taking a week off :-).

The book is divided in 52 concrete pieces of advice. You’ll get ideas for improving your technical abilities, as well as business-related knowledge and inter-personal skills.

A couple of paragraphs I liked, from the Introduction:

For some not-insignificant percentage of IT workers, the safest bet is to start looking for an alternate line of work. […] If you don’t have passion and a drive that would force you to create software […] you’re not going to be able to continue to compete with those who do.

… Software is a business […] To stay employed, you’re going to have to understand how you fit into the business’s plan to make money.

And this one below made me laugh, from advice #6 “Be a specialist”:

“Too many of us seem to believe that specializing in something simply means not knowing about other things.”

I would have titled it something like “The Mature Pragmatic Programmer”, as it is a perfect second volume for “The Pragmatic Programmer” (What? you haven’t read it? Stop reading this stupid blog and go get TPP now!).

Months ago, I was looking for a book on Design Patterns. I already own the great classic GoF and a few more, but I was looking for a more practical, real-world exposition of the classic Patterns. I wanted a book I could recommend to new developers, so they could really learn how to apply the concepts.

I came across Holub On Patterns. I liked it, but I was disappointed with the editorial quality of the book.

I found a long list of errors. Some of them are minor, but still may confuse readers, specially those new to the topic.