Search This Book
- Published by Apress, August 2008
- 416 pages
- ISBN 1430209739
The Good
- Numerous practical examples from the Netbeans API and the JDK.
- Each chapter introduces a concept that could profoundly change your code.
- Practical situations with concrete examples.
- Explanations for novices and experts.
The Bad
- System.out
.println
- Have to read Theory before getting to the practical exapmles.
- Subtitled “Confessions” ?
About the Author
Jaroslav Tulach is the founder and initial architect of NetBeans, later acquired by Sun. As creator of the technology behind NetBeans, he is still with the project to find ways to improve the design skills among all the programmers who contribute to the success of NetBeans open source project.
Intended Audience
Apress.com, the publishers, describe this book as being recommended to every API architect who prefers a bit more engineering design over a purely artistic one. but this book is really much more for anyone who writes code that anyone else consumes – and who doesn’t do that? This book is for any developer who is not brand new to software development.
Selected Chapter Highlights
There are 19 chapters. There are a couple of dull chapters, but by far the majority are very interesting, applicable, and well laid out with introductions and examples of most every concept.
Chapter 1: The Art of Building Modern Software
The first chapter was tough to get through, but it does introduce a key concept of API design and a focus of many discussions throughout the book: cluelessness. Jaroslav suggests that cluelessness supports “the most promising development style.” The pragmatic use of the bulldozer approach: reuse components that are already available, compose applications form big chunks of premade libraries, glue them together, and make sure it works even without fully understanding how it works.
Chapter 2: The Motivation to Create an API
Chapter 2 is important in that it lays out, as the titles states, “The Motivation to Create an API.” This chapter is interesting and fun to read because it lays out exactly why you are reading the book. The biggest point that I took away from this chapter is that APIs are for human beings – for other software developers like yourself – not for computers. And also that not all projects need an API, or at least not a high quality API.
Chapter 5: Do Not Expose More Than You Want
This chapter is the first of many that represent the reason that you bought the book. This chapter starts Part 2 of the book titled, “Practical Design.” Here, Jaroslav begins describing some practical API designs and even some design patterns. We get into applicable sections like “A method is better than a field”, “A factory is better than a constructor”, and “Do not expose deep hierarchies”. This is one of those chapters that you will come back to and read a few times and will refer to in conversation.
Chapter 8: Separate APIs for Clients and Providers
Chapter 8 was one of my favorites. I lead an open source project with both an internal and external API under development and this chapter was right on point for our efforts. This chapter explains the differences between, and how to package APIs for clients and APIs for providers. Jaroslav explains how if you mix your API and SPI together within a single class, then you can never modify the class, stating that adding a method is forbidden because of the contract for SPIs and removing a method is forbidden because the contract for the APIs.
Chapter 10: Cooperating with Other APIs
Chapter 10 discusses how to work with third parties in your application. The key concept that I took away was never to export third party classes through your API. When you do this, you lose control. If the third party changes their API, then your API has changed without you doing anything. A change in a third party could even break your software, or your end-user’s implementation of your software.
Chapter 15: Evolving the API Universe
Chapter 15 introduces methods for changing an API without breaking backwards compatibility. This chapter also describes some tools and techniques that you can use to break compatibility, but to still provide your users with support for the old API by using libraries that provide bridges. Being able to provide new APIs that break backwards compatibility can be very powerful.
Comments
First, my complaints. They are pretty trivial for the most part.
I have to complain about the subtitle, “Confessions of a Java Framework Architect”. Confessions? A confession is “an admission of misdeeds or faults.” The author does describe a few mishaps from the NetBeans API, but I would hardly consider this a book of naughty confessions.
I also have to complain about some of the code examples, but I think this complaint is pretty common among software books with code. Sometimes, commonly accepted software development practices are ignored or left out for the sake of brevity and keeping the example small enough to fit on the page. One of the very first code examples comes on page 47 and in it (and throughout the book), Jaroslav hits us with a System.out.println. Wouldn’t this be like reading a web design book where all the examples used table-based layouts? Doesn’t everyone use some form of logging abstraction. I hate when books don’t follow best practices.
My last complaint is the first four chapters that make up Part 1 “Theory and Justification.” They are all theory are pretty boring. They are tough to get through when you know that if you just skipped a couple chapters you could be reading practical examples with code. There are a few good points and a few things that are good to know before you get to the practical part of the book, but I wish Jaroslav would just make the points and move on the Part 2 “Practical Design”.
I had a few complaints but they are mostly trivial. This truly was a good book. The best part is that the author, Jaroslav Tulach, is the founder of Netbeans and the leader of its API. He has dozens of great examples of good and bad API design from his experience with Netbeans. He describes situations where their API got out of control and how they dealt with it, methods for monitoring your API as a community or team with an API review, and how to avoid API mishaps. Jaroslav has also been around long enough and is so intimate with the evolution of the JDK that he is able to site specific examples in the JDK where changes to the API broke software around the world. Jaroslav is very knowledgeable on the topic and his writing shows it.
The book is full of practical examples. After reading many chapters, I went right to my open source project, Architecture Rules, and either changed code or emailed developer mailing list to suggest changes to code to encourage a better, more malleable and extensible API. I now realize how not only are my interfaces and methods part our API, but so are our file outputs and inputs. Even our exceptions messages are part of our API.
This is without a doubt a book that you need to put on your bookshelf. This is the first book of its kind and the tips and tricks that it provides is timeless – a key attribute of any pragmatic software development book. I encourage you to flip though this book at your local bookstore or just download Chapter 1:
Download the Excerpt
Bookpool.com offers this excerpt: Chapter 1: The Art of Building Modern Software.
Resources
cbang, 
Chris 9:50 pm on September 1, 2008 Permalink
Looks like this should be on the “must read” list of OS developers.
Jaroslav Tulach 8:28 am on September 2, 2008 Permalink
Thanks for nice review. Btw. our blogs are better to be found at http://blogs.apidesign.org
Mike 12:17 pm on September 4, 2008 Permalink
@Jaroslav Tulach – Jaroslav himself. Thanks for commenting.
I’ll be reviewing Pro Java™ EE Spring Patterns: Best Practices and Design Strategies Implementing Java EE Patterns with the Spring Framework
next.
cbang 7:19 am on September 10, 2008 Permalink
A very decent book but it focuses a bit too much on backwards compatibility in my opinion. If you depress easily over this, skip over the first chapters and avoid statements like “simplicity and elegance is not the goal at all”. Also, I was a bit surprised that a book on API design in Java completely fails to mention checked exceptions, considering the scalability and versionability issues involved.