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 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.
14 comments:
Nice review. Mine is over at http://72miles.com/blog/posts/practical-api-design-confessions-of-a-java-framework-architect-book-reivew/
I read it, but I can't say that I felt it was worth the money or time. Its a subject that we need more books on, but I don't think the author did a very good job. There was very little meat to the book and a lot of aspects either missing or not going into the right amount of depth. If anything, it made me think that the Netbeans APIs must be painful to work with. The style didn't groove with me either, such as comparing himself to Newton was a bit much.
Ben Manes>...a lot of aspects either missing or not going into the right amount of depth
Would you mind sharing what you felt is missing?
Ben Manes>...comparing himself to Newton was a bit much.
Oh yeah! I definitely agree on that!
There is nothing bad to compare two objects in systems with linear ordering. There is nothing flaunting to compare 0.1 and 1000000. The result is clear.
In case we assume there is some linear ordering applicable to both, himself and Newton, it does not seem that dare to do the comparison. Until the result is "less than" things are OK. Or am I wrong?
Btw. is the result of book's comparison really "less than"?
Anonymous>Or am I wrong?
I think what Ben and I find a "little much" is coming up with the comparison per se.
Anonymous>Btw. is the result of book's comparison really "less than"?
To be fair, the author put his comparison into the "right" perspective. He actually doesn't compare himself to Newton, rather than his book to Principia Mathematica.
For example, package structure was entirely missing if I recall correctly. I see most people break them up by technical concerns, not behavioral, which leads to procedural vs OO style code. Also, well-defined naming policies are important for large code bases.
Another is metadata. By using it properly, you can remove most of your APIs by allowing people to opt-in. This is an awesome way to reduce the public API, reduce bugs, and simplify code. You infer what they want, rather than being told.
Yet another was the notion that API design only matters for desktop software. There was no mention of SOA. All the same issues come up, like versioning. As he says, you can't just change APIs without compatability. SOA forces this constraint on most of us.
He may have, briefly, discussed contracts. If so, I don't remember it. I am a big fan of design-by-contract. TDD has an impact on API design, too.
And there were lots of things skipped in regards to helping one write elegant APIs (e.g. fluent interfaces, builder pattern, etc). He had a whole chapter discussing his hack that he thought was better than Spring...
Overall, I felt the book's tone was "I don't have an ego, but I'm *really* awesome!". I wanted meat, but instead he toured us through the code he wrote just after graduating from college...
Ben Manes > For example, package structure was entirely missing if I recall correctly. I see most people break them up by technical concerns, not behavioral, which leads to procedural vs OO style code.
You are right, I think talking about package structure was missing. However, he pointed out a number of time, how important modularization is. I think that somewhat relates to this point. If you wanna structure your application into modules, you inherently name your packages in a different way.
Ben Manes > Yet another was the notion that API design only matters for desktop software. There was no mention of SOA. All the same issues come up, like versioning. As he says, you can't just change APIs without compatability. SOA forces this constraint on most of us.
It didn't feel like that to me. I could easily draw parallels to my current project, where I am mostly in charge of server side code. I think his examples and thus his experience are drawn from NetBeans, which after all is a desktop app.
Ben Manes > He had a whole chapter discussing his hack that he thought was better than Spring...
Thank you for mentioning it! It inspired me to write this blog post. I really think that solution is kind of weird...
Ben Manes > Overall, I felt the book's tone was "I don't have an ego, but I'm *really* awesome!". I wanted meat, but instead he toured us through the code he wrote just after graduating from college...
That sounds a little harsh to me, but fair enough! For me this book is, next to Effective Java, a great resource of advices to keep in mind. Yes he made a lot of mistakes, but we all do and I think it's what we can all learn from.
Thank you for your thorough comment. I really appreciate it!
What's wrong with comparing yourself to Newton anyway? He was just another guy himself, who was creative and came up with some cool ideas. So is it bigheaded to compare yourself, being a person, to someone else, who is also a person? I think some people think too much of Newton. He was just some guy.
Thanks for discussing my book!
If you ever feel you want to expand the horizons of the API world, feel free to push them further by publishing what you know. For example http://wiki.apidesign.org is instantly ready at your service.
You know the world won't explore itself, it takes a lot of bright minds to do so. Just like it took in case of physics...
"Another is metadata. By using it properly, you can remove most of your APIs by allowing people to opt-in. This is an awesome way to reduce the public API, reduce bugs, and simplify code. You infer what they want, rather than being told."
Can you make an example. Because the whole XML FileSystem thing appear to me similar to what you're saying.
For what re: packages: well, the whole book is about modules, as NetBeans Platform comes with its own module system. Since modularization poses even stricter constraints than packaging, I don't understand why you find that this topic has been missed.
Last but not least, the book is about the author's personal experience (clarified by the subtitle "confessions of...") as the designer of NetBeans, which is desktop product. It appears clear to me that such a perspective for a book doesn't necessarily cover all the possible fields of software design. BTW, the Platform and most of the things that are described in the book can be used on the server side as well.
For what concerns the comparison with Spring, I agree that DI is better than Service Locator and this is a missing point of the Platform (which is being worked on, BTW). Given that it takes just a few hours of work to implement an annotation system for the Platform, it remains the concept that NetBeans Platform / OSGi concept of "wiring" is much more powerful than the basic Spring Factory. Of course, Spring has dynamic extensions for wiring, which means that which a little work every platform can behave as others.
"Comparing" is not the same as "equating". "Comparing" myself to Isaac Newton, I come up short by about a zillion. "Equating" myself to Isaac Newton makes as much sense as dividing by zero; "does not compute".
I have not read the book, but the negative remarks do not surprise me after reading many of his wiki articles about API design. None of them make much sense.
I don't remember reading any of his API design articles and thinking, "wow, that's brilliant!" I mostly thought, "yikes! that stinks! what an ugly hack! I would definitely fire an employee in my company for doing something like that." I don't like to micromanage programming style. It's just that I have to think about the next poor maintenance programmer that comes along and tries to figure out what the heck is going on.
I am probably am being overly harsh, but its such an important subject I *really* wanted to be wow'd. I was looking forward to an "Effective Java" for API design, or at least that it repeatedly make me smile as I shook my head in agreement. I guess I wanted Bloch's "How to Design a Good API and Why it Matters" presentation in a more flushed out book.
He did spend a good amount of time on emphasising versioning, which was a high point. I disagree in I think one should slowly kill off out-dated code, but I respected his opinion and seperating legacy code into its own module was a good alternative.
While he talked about modularization and the importance of SPI, there were lackings in how to organize them. At the code level, I often see dozens of classes in one package. Most developers seperate them by technical concerns, which promotes a more procedural (action-oriented) style. If done by behavior, the code has fewer utilities and more coordination.
The module structure is also important. An example layering might be frameworks (e.g. persistance), platform services (e.g. user management), domain services (e.g. book service), and cross-cutting utilities (e.g. collections). I don't recall much discussion of modules impact towards the architecture and development thought-process.
Fabrizio, can you help remind me of his XML FileSystem example? I no longer have the book and I do remember him discussing his File APIs. I don't recall the metadata aspects, just the unexpected usages (e.g. toString() for paths).
I should back-peddle a bit and there were definate good points to the book. My favorite chapter was the API Design-fest. That was a very fun read.
I am probably being overly critical, but I had really high expectations. I think Jaroslav expected that, since he commented about the lackings other books on the subject and the hope his would break the ice. To be the first one to give it a real shot takes guts and is commendable. But you'll have people like me who have been eagerly looking forward to one years, and really do want the next "Principia". It should have been the next "Design Patterns" book, something to really love. So admittedly I had too high of an expectation.
Ben Manes > Fabrizio, can you help remind me of his XML FileSystem example? I no longer have the book and I do remember him discussing his File APIs. I don't recall the metadata aspects, just the unexpected usages (e.g. toString() for paths).
He writes about the FileSystem abstraction in NetBeans quite a bit in the book. I think it makes a great example. However, I would be interested if you could give us an example what your understanding of metadata is?
Post a Comment