ThanksReviewers

From APIDesign

Revision as of 22:02, 10 July 2008

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 now, 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. We needed to finish a compulsory student project and decided to create a Delphi for wikipedia::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 such project. Luckily, we knew Adam, a visiting professor not knowing exactly what it takes to lead seven students and their project. 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, however 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!" Sure, Dave, you designed a lot of APIs, it is easy for him 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: The 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 scientific methods I learn 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 TheAPIDesign book. 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

TBD: long time user, visitor

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

TBD: