ThanksReviewers
From APIDesign
Contents |
Reviewers
When the first version of TheAPIBook was written, and corrected by Geertjan and Patrick, we needed few experts to review the content and catch and help eliminate silly mistakes in code samples, terminology, etc. With a little help from Geertjan I've assembled an invitation, send it to few selected individuals. The following guys generously accepted to to take a look at TheAPIBook. I'd like to thank them all, as I believe that without their help, the book would not be as good as it is now.
AndreiBadea
I wanted Andrei to be the reviewer for few reasons. He works on NetBeans, he knows the style and processes we use to develop APIs, he also knows how to design APIs. However he also likes to argue about everything. I really mean argue, not complain. Except rare occasions, his comments are rational, useful and sharp. It is useful to think about them, evaluate them. I was sure his comments to my book will be exactly like that: sharp, valuable and worth considering.
Indeed this was true. Andrei provided a lot of comments to various code samples, their formatting and code style consistency. I could argue with him that the internals of API do not matter, that the code inside the methods bodies does not need to be well formatted, that it only needs to work. No luck. He literally forced me to rewrite almost all the examples to be nicer claiming that such inconsistencies are not present in Effective Java at all. Thanks Andrei for spotting so many issues and making most of the code samples better.
An interesting point of view can be obtained speculating about reasons why Andrei accepted being a reviewer. Once I mentioned to him that I'd like Josh Bloch to be the reviewer as well. At the end this did not work out, still that point of time might be the moment when Andrei decided to help me: My name starts with B, his name starts with B, imagine I would be printed next to Josh in a single book! Sorry Andrei, that I did not manage to make this happen, and take this paragraph as my apology. Enjoy being mentioned next to Josh at least in one paragraph!
AdamDingle
As you may know the roots of NetBeans can be traced to 1995, when seven of us, students of Faculty of Mathematics and Physics at Charles University in Prague needed to finish a compulsory student project and decided to create a Delphi for XWindow system. The idea was there, however we needed a guidance. A teacher that would lead the project. We quickly found out that no Czech teacher is fool enough to try to lead us. Luckily, we knew Adam, a visiting professor not knowing exactly what it takes to lead seven students and their never-ending work. That is why, when Adam agreed, he became the grand father of NetBeans. Without his help we would not have NetBeans, and I could never finish TheAPIBook. Thanks Adam.
When Adam returned back to U.S., he disappeared from our radar for few years. However at the end of last year, he re-appeared on our mailing list and confessed to use NetBeans IDE. I was really glad to see him and I thought, OK, it would be very nice to get Adam to be a reviewer. He helped start NetBeans and now he can also review the wisdom we generated over the years. I think it was a great choice to invite Adam. Although he is emotionally attached with the project, he does not know anything about its organization, about its code and about its APIs, as such he can play a perfect role of patient external reviewer. He did that perfectly. I remember getting comments like: "this section is too much NetBeans centric, this one is not generic enough". Based on this advice I rewrote a lot of the text to not mention NetBeans at all, or at least explain that the topic is generic enough. Thanks Adam, for making the content of TheAPIBook more generally acceptable.
DaveKoelle
In the scale of our reviewers, we needed some really skilled Java API designer, moreover one that would not be connected to NetBeans at all. GeertjanWielenga recommended Dave, the API design guru behind JFugue musical library. I can hardly imagine someone better playing Dave's role. He acted like real API designer. Skilled, fast, sharp in his reviews and always ready to jump to the gory details of individual code samples. I remember Dave sending comments like Common, I do not need you to tell me what is API, I already know it, just show me the real API code! Sure, Dave, you designed a lot of APIs, it is easy for you to understand the basics, but we need to get everyone on the same starting line, so please bear with me, you'll get what you want!
As Dave received more and more chapters, his complains slowly fade away. However, as Dave is typical API designer, they were not replaced by clamours of happiness. For a few weeks I was not really sure whether Dave really liked the book or not. However when we met during JavaOne 2008, he said something like: Chapter 18, Extensible Visitor Pattern Case Study is really nice summary of all the content of the book, all the advices suddenly emerged and played very nicely together. I am glad for these words. I was not really sure if the chapter 18 is not too complex, however since Dave's comment I know it is not. Thanks Dave helping me realize that!
MartinRinard
Martin is the inventor of term Cluelessness, at least in my eyes. When I saw his presentation at OOPSLA 2006, I was amazed and shocked. His advices were so ugly, but so true, that I could not stop thinking about them. I was thinking about relation between reliability and Cluelessness, about importance of testing and also about the role APIs play in the attempt to increase Cluelessness while improving quality of our applications. At that time I realized that Cluelessness is great meta principle that allows us to evaluate whether an advice is good or not. If something allows people to achieve more while knowing less, then the thing is good. Thanks Martin for inventing such meta principle!
An interesting moment occurred when Martin finished reading first half of the book and said: Your book talks about Cluelessness, but it cannot be read in clueless mode itself! A perfect observation, which I knew somewhere in my brain, but I did not realize it until Martin revealed it. Yes, I love Cluelessness, I want to see Cluelessness everywhere in software development. However when thinking about it and describing it, I automatically applied the like to be scientific methods I learned at European Universities: Theory first, practical applications later. As a result this book does not teach how to design APIs cluelessly, with as little understanding as possible. Instead it sees properly designed APIs as a tool to help other developers to practice Cluelessness. However the API designers themselves need to think about what they do quite a lot.
Martin, as the inventor and great propagator of Cluelessness naturally expected this book to be written in clueless mode, for people in hurry, without need of deeper understanding. This resulted in false expectations, which could not be satisfied by TheAPIBook. I'd be glad to advice to design APIs cluelessly, however I still do not know how to do it properly. That is why I at least tried to set the reader expectations right as soon as possible and warn and straight things up. Thanks Martin for pointing this out, hopefully the changes I've made according to your suggestions will prevent wider disappointments due to readers' false expectations.
Rich Unger
Rich is long time NetBeans Platform user and as such he had to go through all the suffering associated with using NetBeans APIs. He started to use NetBeans platform in version 3.2 or so, which was possible, but hard. In fact there was no support from the NetBeans IDE for developers like Rich. Together we tried to fulfill the need for this by giving frequent presentations describing the necessary tricks when using the NetBeans Platform. These presentations stop being necessary when we created new wizards that remove the need to understand all these tricks. This adventure helped me realize that the wizard is the best API as mentioned in Chapter 9, Keep Testability In Mind. Thanks Rich for talking this wisdom out of me.
Rich also was the first external NetBeans developer who tried to contribute to our APIs via the APIReview process, as described in Chapter 16, Teamwork. After reading the chapter, Rich told me that he liked the secret behind the history of the APIReview process invention. Rich also asked whether I got some punishment for revealing the secret. Well, I did not, as nobody affected read the book yet, but I'll keep you posted. Thanks Rich for practising the APIReviews with us.
TomWheeler
Tom is long time NetBeans user, building applications on top of NetBeans Platform for Boeing. He knows NetBeans APIs well, as he is building upon them, however not only that, he is also an architect! He builds Boeing NetBeans Platform that is then consumed by millions of Boeing developers to create their desktop applications. In some sense, the next Boeing airplane is going to be build with NetBeans. Thanks Tom for making me feel more proud next time I use your airplanes.
I knew Tom as a very good speaker. I could not imagine someone who handles English so well, could be bad reviewer and indeed, I received just valuable comments by Tom. However I selected Tom for yet another reason: Just like me, he is architect working in a team. He needs to guide his team members, tell them how to design properly, verify that they understand. That is why I expected unique comments from Tom and I was not wrong. When Tom visited Prague last time, he told me: When I was reading through the book, I was always wondering how do I practice these design skills with my team, and then I came to Chapter 17, Using Games to Improve API Design Skills, and suddenly the answer was clear! When I assembled the book, I was not sure whether to include Chapter 17 or not, so thanks a lot Tom, for saying these words and confirming that my decision was right.
JesseGlick
Jesse joined the NetBeans project in 1998 to write technical documentation. As a result he was reading through the NetBeans APIs of that time, mostly created by me and documenting them (at that period of time we were not yet practising the use case driven API design as popularized by Chapter 3, Determining What Makes a Good API). As API is all about communication, his work was essential for the success of NetBeans project. Thanks Jesse, for doing that.
However, Jesse did not stop on the level of documenting my APIs, he also started to write his own. In fact he is architect of quite a big portion of NetBeans IDE. Jesse's adventures during the API design motivated many observations and conclusions present in TheAPIBook. Whenever we argued about APIs with each other or with other persons, I've taken notes, added a paragraph or two. Sometimes I even directly copied Jesse's email into the raw book's material. For example the Do Not Put Setters Where They Do Not Belong in Chapter 5, Do Not Expose More Than You Want is heavily based on one such email conversation.
Jesse speaks a special kind of English, at least from my point of view. It is always pleasure to read it. That is why I have always found it a sad that Jesse keeps all his notes in emails and does not publish them for everyone to see. That is why I am very happy about Jesse's decision to join the API Design blogosphere. Thanks Jesse for all your past and future notes.
