Jaroslav Tulach (pictured, left), the author of the recently released "Practical API Design: Confessions of a Java Framework Architect", published by Apress, is one of the founders of NetBeans and the lead architect of the NetBeans APIs.
Below, Jaroslav Tulach introduces you to his book and shares with you some insights relating to API design.
Note: A complementary chapter of his book is available here via the related Apress site. The chapter is "Chapter 1: The Art of Building Modern Software". In addition, Jaroslav has started participating in the monthly NetBeans Podcast, where he shares an "API design tip" in every episode. The most recent NetBeans Podcast episode can be found here.
Hi Jaroslav, can you start by telling us who you are?
I see. :-) This is the usual question that is supposed to convince readers that they should listen to me. This is always delicate to do right and even harder for someone who's name is totally unreadable to the English speaker. I've faced this problem many times before, such as when creating the cover of my book. Just follow this link to read more about me. And here's the summary: I really have something to tell and I did my best to tell it in an entertaining way!
You've written a book about "API design". Why did you write it?
There are many answers to this question. The need to write this book gradually increased over time. However, a turning point came when I was at a family event, talking with a cousin about my hesitation regarding the writing of a book. He asked: "So, you know something that nobody else does, you can write it down, you have potential publishers... and yet you're still hesitating? That's just weird! Start writing!" That was the point where I made the decision that I would identify a suitable publisher and write and publish the book.
Now, let's talk about the book itself. What is an API, exactly?
"Exactly?" Well, an API is about communication. Surprisingly, it is not related to communication between the developer and the computer. It is human to human chat. As such, the question "what is an API" has a very, very broad answer. Everything that helps two developers to communicate can, and should, be seen as an API... the structure of a database, the location of various files on disk, their content, the ports your application listens to, the URL of your server, etc.
So this is a book specifically for people who design APIs?
It is for developers who want to talk to other developers. A simplified guess tells me that this includes almost everyone writing code and sharing it with their team. I have separated the book into three parts. Part one deals with general aspects of an API, builds up a vocabulary of what an API is and how to measure its quality. Then there is a practical part showing various API design patterns in action. The last part shows how the advice given in the previous chapters works in real life, how to organize work in teams that design APIs, and what compromises one has to make. In addition to these three parts, I've also added a small prologue and epilogue to put the three parts into a proper context.
Here's what the start of the freely available chapter 1 looks like:
What can one learn from the book?
My former manager used to say: "Good judgment comes from experience. Experience comes from bad judgment". I believe that at this point the NetBeans team has mastered API design skills to quite a high level. However, this has not come about magically. We needed to make a lot of mistakes in the last ten years to get to our current state of understanding. By reading this book, you'll get a chance to not repeat some of these mistakes, while improving your API design judgment.
Do you have one or two tips to share with us as an example?
It is always hard to choose a tip or two, as that may create the illusion that these two are more important than others, and that it is enough to learn just these two to get good results. I do not know two such "magic" tips.
Still, if I absolutely must select one or two observations to highlight, I'd name these:
- "The first version of an API is never perfect."
- "You cannot know all the users of your library."
These two axioms capture the basic difference between building a library with an API and building an in-house system. APIs are like stars, once discovered, they need to stay and shine for ever. They cannot disappear suddenly and randomly. That would break the trust established in your communication and the rules of proper design. Libraries need to evolve according to the rules of the API design universe.
What do you hope readers of the book will gain from reading it?
More than anything, I'd like to start and contribute to a broader discussion on API design. I believe that it is an essential topic, important for the development of modern software. Not enough attention has been paid to it, nor on how it differs from regular, in-house coding. Please visit http://wiki.apidesign.org and share your experiences with me and others there!
I can see more and more (mainly) open source libraries being developed by a growing number of developers. I'd like to save all those framework maintainers a bit of time, before they begin reinventing the wheel. I'd like all of us to share experiences and use methodologies that are known to work. By doing that, we will get better libraries and better libraries mean better applications built upon them.
Last, but not least, I believe that the previously mentioned axiom of one's inability to know all one's users is very useful, even in in-house software development, and even when you, in fact, do know all your users. By getting ready for evolution from the very beginning of the coding of our systems, we can save a lot of maintenance troubles when we release newer versions. I believe that particularly teams consisting of 30 or more programmers working together can benefit from adopting some of the API design methodologies discussed in the book.
What was it like to write this book? How long did it take? Did you enjoy it?
I had been collecting notes over the past ten years, so I knew for quite some time what I wanted to write about. After the abovementioned turning point initiated by my relative last summer, it took just a year to sort and polish everything. I am glad that, now, a year later, the book is available and I am thankful to everyone who helped me reach the publication date. By the way, if you want to know more about that, visit http://thanks.apidesign.org.
Do you have tips for others writing programming-related books?
Well, I've noticed that books about programming do not use syntax coloring. I mean that keywords are not bold and operators and strings are no different from regular text. I noticed that accidentally, but as soon as I realized it, I decided that my book would have proper "coloring" of code samples. It was not really easy to make that happen, as my publisher never noticed either and was not ready for that, but I believe that at the end we succeeded. All code samples in the book are "colorified in grey" and I consider them nicer and a bit more natural to read. So my tip is: if you write your programming related book, make sure you "colorify" your code samples as well!
Do you have anything else to share with us?
Share! I mean, let's share together. I believe I know a lot about API design, but I am quite sure I know almost nothing about it as well, at the same time. The API design world needs deeper exploration and I'd like you all join that journey of discovery. If you have tips, advice, observations, patterns, please feel free to visit http://wiki.apidesign.org and share them with us. We need that knowledge to make software development of future more easy and more reliable.