Practical API Design: Confessions of a Java Framework Architect

After 15 years of writing vague, unclear and verbose "manuals" of the type "you don't have to bother thinking", someone from SUN explains why they had written their API that particular way. Why is it called "Confessions"? Did they plot to hide that information from the beginning? Or explaining their reasoning is considered to be shameful in some circles? Anyway, thanks to the author for finally shedding light on the way SUN designed their API. It took a great burden from my soul, because I always missed connection points in their manuals.

Wish there were more books like this.

I have started reading this book, and after a while i realized that it is definitely not a fun to read this book. You need to spend lot of time to get little knowledge.

If you are willing to change your devlopment way of yhingking you can achieve great results in about the same time as linear development

Many books explain how to write programs in a given computer language, though books that describe how best to structure those programs are much less common. Practical API Design stands apart from either category in that it teaches how to create the building blocks upon which other developers will base their applications. The focus of this book is on how you can design software that evolves to meet changing requirements and technology. Although the examples are primarily in Java, the advice in the book transcends any computer language and will be valuable to any developer who creates libraries or frameworks on which others rely. The book describes how to create intuitive APIs, ideas for improving performance through API design, tools for testing compatibility and tricks for compatible evolution. As the principal designer of the NetBeans Platform (a software framework used by hundreds of organizations, including many Fortune 500 companies), the author certainly knows the topic well. He covers the problems faced when designing APIs, then illustrates them with real-life examples of how to solve them. His thoughtful assessments of what has -- and has not -- been successful for the APIs he has designed allows the reader to benefit from his many years of experience. In summary, this is an excellent book and I'm not aware of any other which covers these topics with the same depth and passion. I've given it four stars for only one reason: it could be more concise. It sometimes embarks on tangents which, while interesting, don't seem to reinforce the main points. Full disclosure: I'm an active NetBeans Platform developer and I know the author personally. At his request, I served as a technical reviewer for the manuscript of this book. Although the publisher sent me a free copy of the book following publication, I received no other compensation and feel that the review I've given here is honest and unbiased.

I'm not sure what I was expecting. This book is part memoir about the creation and evolution of NetBeans, part list of best practices (and a few esoteric tricks), and part philosophical discussion, making analogy between the development of an API and the birth of modern physics. In the end, I was somewhat baffled. But then, I'm not in charge of a large, popular Java API. I would recommend this book only to that handful of programmers who fit that description.

Practical API Design: Confessions of a Java Framework Architect is the book I've always been waiting for. Jaroslav Tulach, the founder and architect of NetBeans, created a highly recommend read for everyone in charge of developing APIs. But even if it's not your job to define interfaces, you are somewhat alway on the other side consuming them and it's good to know what drives evolution of the APIs you work with. The book consists of 3 parts: Part 1 is called "Theory and Justification". It defines the terminology and background which gives you the necessary foundation to explain and justify API design. Let me give you and example: Have you ever had problems explaining your design to a colleague? You couldn't find the right words to reasonably highlight your decision, but you know it was right? The only justification was your intuition and the feeling that your design was the right choice. Does that sound familiar? That's where Part 1 of this book comes in and tries to give you a tool to justify and even measure the quality of your design decisions: Selective Cluelessness. It's a principle which is based on the assumption that you can achieve more by knowing less: "The more good APIs we have, the bigger the systems we'll be able to build without understanding all their details." "Practical Design" is Part 2 and basically puts the theory highlighted in the first part to practice. Using Java, the author provides a set of what he calls API design patterns. They are design patterns in the traditional sense, but with a focus on evolution. Most of them accompanied by an examples the the NetBeans APIs. It doesn't matter if you are not familiar with NetBeans. Due to the author's years of experience with NetBeans, he does a great job explaining the problems it was facing and how they came with a solution, which evolved into an API design pattern. ..., it's slightly more complicated to design a universe than building a house. As a result, we need an enhanced version of the design patters. We need patterns that help us building a "universe". Part 3 of the book, "Daily Life", is a collection of advices on how to bugfix, evolve and maintain an API. The author points out how important versioning is and how NetBeans solves such a problem. He highlights the importance of compatibility and how to keep the promises to the users of your APIs. The theory and initial design are just the tip of the iceberg. The rest is the real work. I'm really glad I read this book, although it took me quite a while. The reason is not the 365 pages. It was all the moments I had during reading it. So many times I was reminded of mistakes I made in APIs I previously designed. I often pondered on whether a solution suggested in the book was better than the one I came up with. I think that's what makes a book interesting, if it makes you think and critically review your own solutions. I enjoyed taking the journey through the API universe and learning how to design an API in a selective cluelessness way. As for the reasons why you should read this book: ... when you understand the API world, its needs and its laws of evolution, you can shape it into a form containing all that the creators of the oldest and most perfect science always searched for - beauty, truth and elegance. A properly API universe ain't a bad place to be.

Verbose, not so good examples (sometimes hard to follow), strange formatting, sometimes interesting.

This book is up there with Joshua's book on Java. Not an easy reading I have to admit, unless you key in some of the examples in your IDE ( at least for me!) it does not condense well!. One of the core part of the programming is API design. When it is done at an industrial level, it require quite lot of 'thinking' up front. Usually it takes lots of failures (and many sleepless nights) before you can get it right ( in your n'th iteration). If you have experienced this already or about to embark on it, this book is a must read!. I wish author had given more code snippets and examples to demonstrate the theory. But even in this form this will be an excellent addition to your library