CElliott (12) [Avatar] Offline
#1
Will you please put some or all of the ideas in Henning, M. (2007). API Design Matters. ACM Queue, 5(4), 24-36 into The Design of Everyday APIs. I could not finish Irresistible APIs and promised never to look at it again because I could not find any of the classical ideas about API design in it, and, of course, no amount of pounding on my desk, the keyboard or the computer could make the examples work.

API design is important to computer programmers because they deal with it every day in their work, using the C++ Standard Library, the Java Documentation, Mathematica, old LISP manuals, The Collected Algorithms of the ACM, etc., etc., etc. It is also important that APIs be maintainable and maintained. You cannot just throw new routines at a library without any thought of consistency of presentation, organization, encouraging use, and people finding them again. There is no point in proselytizing code reuse if programmers can't find the stuff again and the documentation is not clear, concise, and complete.

I any case, I wish you the best of luck with your book. Speed of completing the work may not be important. What may be most important is that it be a great book that you and the rest of the world treasure for a very long time.
Arnaud Lauret (10) [Avatar] Offline
#2
To the request "Will you please put some or all of the ideas in Henning, M. (2007). API Design Matters. ACM Queue, 5(4), 24-36 into The Design of Everyday APIs", I answer "Yes! Definitely!".

I didn't knew this article and found it on queue.acm.org. It's really an interesting one for people willing to read my book. The Design of Everyday APIs is about Web APIs and not "library APIs", but this article and my book share the same spirit and these two types of APIs share the same basic design principles.
Here are some quotes from the article that I particularly liked:
APIs should be designed from the perspective of the caller.
APIs should be documented before they are implemented.
Good APIs are ergonomic.
An API must provide sufficient functionality for the caller to achieve its task.
An API should be minimal, without imposing undue inconvenience on the caller.


All these topics are discussed in the Design of Everyday APIs. I describe the consumer's (or user or caller) perspective vs provider's perspective in chapter 2 (Designing an API for its users). Ergonomics is the backbone of the book and is explored in depth in chapter 2, 5 (simple APIs), 6 (predictable APIs) and 7 (Intelligible APIs). Documentation is discussed in chapter 3 (describing an API) and 11 (Growing an API).

Thank you very much for pointing me out this article and for your support!
Arnaud Lauret (10) [Avatar] Offline
#3
And some other quotes (definitely a great article smilie):

It takes time and a healthy dose of "once burned, twice shy" to gather the expertise that is necessary to do better. Unfortunately, the industry trend is to promote precisely its most experienced people away from programming, just when they could put their accumulated expertise to good use.

The idea of the book is to lessen the "once burned, twice shy" thing smilie, so many of my burns could have been easily avoided.

The effects of poor APIs, however, go far beyond inefficient code: poor APIs are harder to understand and more difficult to work with than good ones.

See chapter 1 which is available freely.

Much of software development is about creating abstractions, and APIs are the visible interfaces to these abstractions. Abstractions reduce complexity because they throw away irrelevant detail and retain only the information that is necessary for a particular job

This is the core topic of chapter 2.