Blogs:JaroslavTulach:Daily Life

From APIDesign

Daily Life Blog

Torrented!

From time to time I search the Internet to see whether there are some new reactions to my book. Yesterday I searched again and to my surprise I found a torrent of the Practical API Design book. Somebody had to think the text is so valuable that it shall be shared!

Now I am in the same group as musicians and movie stars, my work is being copied! Without royalties, but it still makes me proud. Is there anything better for a book author than knowing that his book is read by someone? As one reader attracted by the online version puts it: Look at the upside. If I didn't come across the PDF, I probably wouldn't have ever discovered your book and forked over the $60 for the hardcopy. :-)

In case you get the same feeling after scanning through the torrent version, don't hesitate to order via amazon and/or stopping by to get written dedication.

Enjoy API Design!

<comments/>

Comments So Far

I've got a legally-obtained printed copy. I hope this means I can get you to sign it when I see you again!

--Tomwheeler 17:31, 16 August 2009 (UTC)

Indeed! Don't you want to see more from Prague, Tom ;-?

--JaroslavTulach 06:45, 17 August 2009 (UTC)

It's a common practice of mine:

1) search torrents for an argument of interest 2) download all 3) evaluate all 4) buy the hard copy (or the digital one) of the valuable ones.

I hate buying dummy books (or books for dummies;). I also hate pirating...

Obviously, I have the hard copy of Practical API Design on my desk, but I ordered it bypassing the usual workflow - no fear about the value, here!

Sergio

It is hard to keep appropriate level of humility after reading such comment. Thanks, Sergio.

--JaroslavTulach 12:18, 3 November 2010 (UTC)

--JaroslavTulach 14:37, 16 August 2009 (UTC)

Scala can't be so bad!

My recent rant about the missing slickness of Scala's core libraries finally provoked a reaction. Thanks Landei for speaking up. I know there no black&white in the real world, but your explanation of Scala's "flexibility" could be extrapolated to a false (at least in my opinion) feeling that Scala is not yet ready for real production use.

--JaroslavTulach 08:30, 12 August 2009 (UTC)

Sigtest for C/C++

An anonymous coward just provided a link to signature testing tool for C and C++. Good to see the set of API tools to expand beyond the Java world.

--JaroslavTulach 19:18, 9 August 2009 (UTC)

Welcome to Performance Team!

Another NetBeans release cycle is in progress and it is time to write future press release (as advocated in Chapter 16, Convincing developers to document their API). Take a look so you know what to expect as soon as NetBeans 6.8 is out!

--JaroslavTulach 15:53, 16 July 2009 (UTC)

Speed Your Application Up

Here is description of a class loading cache that has potential to drastically speed up start of any application composed of many JAR files. See its benefits on your own and learn to use them in your applications!

--JaroslavTulach 14:35, 14 July 2009 (UTC)

Press Release: NetBeans 6.7

Are engineers capable to produce a press release? Possibly, however as explained in Chapter 14, it needs to be written before the coding starts. Read what we have written six months ago and celebrate with us NetBeans 6.7!

--JaroslavTulach 10:09, 7 July 2009 (UTC)

API Podcast #5: Can you win?

Here is another podcast recorded to explain importance of playing games while learning to design APIs. Ask yourself today: Can you win an API Fest with a change like this?

--JaroslavTulach 09:37, 2 July 2009 (UTC)

XML SAX and DOM 2

Few years ago our meta modeling gurus submitted a proposal for JavaOne BOF named XML SAX and DOM 2. They wanted to describe NetBeans MOF solution and show how good it is compared to standard XML tools. I always admired the name of the talk (as the JavaOne was dedicated to show the synergy between XML and Java it obviously was rejected) and I am glad I have a chance to use the title today too: I just managed to remove XML from Java.

--JaroslavTulach 09:56, 26 June 2009 (UTC)

Building the Modular Java SE

Modular Java SE has its own Hudson Builder - check the first artifacts: base.jar, applet.jar, corba.jar, deprecated7.jar...

--JaroslavTulach 21:23, 21 June 2009 (UTC)

Aliens vs. Predators. Bridge between OSGi and NetBeans.

Many said this was impossible. Many said this would be crazy. Many said it cannot work. However it does work like a charm. I am glad to announce that I have a well working OSGiAndNetBeans bridge and I am ready to build community around it.

--JaroslavTulach 10:35, 2 June 2009 (UTC)

API Podcast #4: Diamonds vs. Stars

Do you want to know why core Java people believe APIs are like diamonds? Enjoy this API Design Tips podcast at least as much as we enjoyed it while recording it with Geertjan!

--JaroslavTulach 20:43, 31 May 2009 (UTC)

Scala Libraries Rant

I've been asked by a colleague what I think about Scala. I think I like it, but...

--JaroslavTulach 15:04, 28 May 2009 (UTC)

API Podcast #2: Reentrancy

API PodCast #1

Mercurial vs. Subversion. Correctness vs. Simplicity.

I have dedicated one side note in the Practical API Design book to Mercurial_vs._Subversion comparison. Last week I received a comment from TheAPIBook's reader claiming that the Mercurial and Subversion behaves the same in this particular respect. So I needed to run an experiment. They are not same at all! One is correct, the second is simple to use. Which one is better?

--JaroslavTulach 16:29, 5 April 2009 (UTC)

Colors that You Like

Some of you asked for Black on White colors for this website. Now you can have them: Find Black/White symbol in the left navigation bar to make temporary switch or log in an choose your preferred skin in your preferences.

--JaroslavTulach 11:23, 4 April 2009 (UTC)

What's your big brother's name? AOP!?

Do you control complexity of your application? What tool do you use? Something homemade, something bought or something general like AOP?

--JaroslavTulach 10:03, 22 March 2009 (UTC)

sigtest 2.1 released!

The new version of the absolutely necessary tool for executing SignatureTests has just been released. Enjoy!

--JaroslavTulach 19:37, 17 March 2009 (UTC)

Extreme API Fest

Petr Šmíd just finished his API Fest game for HP Prague developers. I really enjoyed observing the players and I have to admit I learned few tricks myself. Read more about the HPAPIFest09!

--JaroslavTulach 20:43, 9 March 2009 (UTC)

The Definitive Guide to API Design

I have to mention that I've been pointed to another review of the Practical API Design book. Very nice read, I was pleased to hear the book was useful. But then, I got to the comments section. Well, that did not feel pleasant anymore. For a while I was searching for a rope and a tree to hung and lynch myself.

However after thinking about it for a bit more, I believe that I do not need to persecute myself for writing the book. I knew the book is not complete, I knew its selection of topics is subjective and related to my own experience (hence the word Practical in the title), yet the book is still more useful out than kept just in my head and notes.

Update from March 7, 2009:

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.

The later comments made me feel a bit better and the one quoted above reminded me of a story related to the book's publication. My publisher's favorite title of the book was Definitive Guide to API Design. It took me quite a lot arguing and I even needed to meet Apress boss, Dominic, to change their mind. My book can be attributed with various adjectives, but it is not definitive at all. Take this note to correct your expectations. Don't expect definitive answers to everything related to API design. Expect that your horizons in the API world will be enlarged and many things will be more clearly recognizable. But many questions will remain.

I have to repeat the theme of the epilogue: The exploration of the API world is just starting. If you have something to say about API design and you are not afraid to contribute to a wiki, feel free to join the wiki.apidesign.org. If you have ideas about various APITypes or APIDesignPatterns or related topics don't let them be buried in Blogs, put them into wiki - wikis are like stars, they are forever. Almost.

--JaroslavTulach 20:12, 7 March 2009 (UTC)

Tell me your name! I'll tell you how good designer you can be!

Well, not really. But Good Names are important. Here is little video to prove that.

--JaroslavTulach 14:15, 26 January 2009 (UTC)

Painful Reading Days are Over!

If you ever suffered while reading files in Java, please accept my sympathy and enjoy the recently proposed NetBeans API improvements.

--JaroslavTulach 18:11, 23 January 2009 (UTC)

PF 2009: Get on Board!

Dear readers of my book and my blog, I've mentioned in Epilogue of TheAPIBook that I good tools can help anyone do better job. I backed my reasoning by a skiing parallel. Recently I found an old video to explain what I really meant. Thanks for your interest in API Design and I wish you good tools in 2009 to help you get on the board!

--JaroslavTulach 14:20, 29 December 2008 (UTC)

Did OSGi Comrades Make a Mistake?

Many systems store their configuration in some form of property files. However a lot of them is not doing that really properly. The results can then be quite painful. Just like when I recently played with OSGi manifest files. Read my story and feel my pain...

--JaroslavTulach 12:36, 16 December 2008 (UTC)

2009: The Year of Annotations

As I noted recently, I see the year 2009 as the year of annotations. The NetBeans project is about to rely on them more heavily. Finally! We've been waiting for that for ages, but finally we can compile with JDK 1.6 JavaC and we can use compile time annotation processors. As a result we can replace our layer based registrations with annotations and benefit from compile type checking, code completion, from having the registrations in the same place as the code that is being registered, etc. Also we can offer our API users simple looking annotations and let associated annotation processors do more advanced and more effective processing. As a result the developers have simple API to deal with, while actual registration hidden behind can be as effective as possible, even at the cost of complexity, but without compromises to reliability (as the complexity is kept in the processing infrastructure, not exposed to API users).

The other project related to annotations that we are likely to incorporate during 2009 is our extended use of Annotations for Software Defect Detection. This is heavily based on the JSR 305, yet until it is stable we do not want to expose such unstable API to users of our stable APIs (more on that in Chapter 10, in section Beware of Using Other APIs). As such we are going to create our own annotations (still recognizable by FindBugs and co.). The hope is that our annotation will stay compatible even if the underlaying JSR 305 slightly changes. Please find our current patch and comment here or in the issue 137437.

Last project that deals with annotations is developed by our editor hints guru Jan Lahoda - its aim is to bring complex refactoring to masses! How? Why? We have observed that using @Deprecated annotation is good hint to help your API users recognize that some part of your API is obsolete and shall no longer be used, however that in no way helps users of your API with converting their code to new, non-deprecated style. We have a solution: Use Code Transformation Annotations! Dear [API] writers, let's adopt these annotations and use them in your API! They are completely standalone (read more), lightweight and we are ready to incorporate feedback of everyone interested in the project. Indeed, my plan is to bring these easy to use and flexible refactorings to NetBeans soon, hopefully for version 7.0.

So these are my three annotation related projects. I find them quite exciting and I cannot wait to see them being used. Annotations are here to simplify life of API users and developers. As soon as we have them, we will have full right to call the year 2009 the year of annotations!

See APIFest08 winners photos!

See the winners and sponsors of the game on the pictures taken by Jan Chalupa.

--JaroslavTulach 16:10, 31 October 2008 (UTC)

NetBeans 6.5 Performance Press Release

How can one announce to the world that something important happened? Via Press Release, of course! However, one question stays: who can write good press release? Engineers are generally seen as incapable of doing so, however as argued in Chapter 14, Paradoxes of API Design, there is a way to help them: Force them to write documentation or press release before they start to code!

This is the Press Release of the [NetBeans] performance team written six months ago. Now, when the release of [NetBeans] IDE 6.5 is near, it is time to publish it. Feel free to read what we planed and what we delivered!

--JaroslavTulach 14:47, 30 October 2008 (UTC)

Jan Žák and Petr Šmíd are winners of APIFest08

It is time to announce results of APIFest'08.

--JaroslavTulach 11:44, 26 October 2008 (UTC)

Petr Šmíd's Thanks

I would like to thank you very much for organizing the competition.

Unlike all other programming competitions which are focused on creating algorithms this one is unique, because it focuses on another type of problems which more reflects real challenges that programmers deals with.

I can personally say that I learned many lessons about API design and I think this is the case of everyone who joined this event.

That's why I can suggest everybody to join this event next time. It was well prepared and the idea of the competition is really great.

So thank You Jaroslav and all guys which are behind the event!

--Petr.smid 13:00, 29 October 2008 (UTC)

The Most Insightful Review of "Practical API Design"

The longest, most detailed and insightful review I have seen so far has been written by Tim Band for Lambda The Ultimate.

--JaroslavTulach 11:27, 24 October 2008 (UTC)

APIFest08 Judgment Day/Week Starts!

The judgment day is here! Dear APIFest08 participants, during the last rounds, you were concentrated on making your own solution perfect. However since today you will have to stop looking just at your own solution, you will need to start digging in solutions provided by others to find possible evolution mistakes. This is a new task, different to what you have done so far, but I hope you'll make it. Because only if you find mistakes in solutions provided by others you will be allowed to win TheAPIBook.

If your own solution is found backward compatible and it successfully passed the 4th round, you'll be awarded with 10 points. By default you all have those points. However you can be awarded with 1 point by showing compatibility problems in each solution provided by someone else, who advanced to 4th round. Of course, in case somebody finds such problem, the author of the solution looses own 10 points. As I wrote in the last post, I know that at least five solutions have some problems, so do not give up and seek for them! Your points are waiting! Also please note that the fact that I may know about a problem of your solutions does not mean other participants are going to find it. Don't give up and good luck!

First of all you need to setup your working environment:

# create the repository
hg clone http://source.apidesign.org/hg/apifest08/
# or update it
hg pull; hg update
# create directory named by you Joe Hacker would have:
mkdir taskx/jhacker

and now your hunt can start. Repeat following tasks as many times you wish. First of all somehow select the solution you want to find problem in. Usually I use a diff:

diff -ru task2/solution03 task3/solution03

Each difference is potential candidate for compatibility problem. It is just necessary to write code against the old API that does something different in the new version. If I notice some potential evolution problem, then I setup the against project and write a test into it to show the error:

# select the solution you want to break, let supposed it is #3:
hg copy taskx/jtulach/against-solutionXY/ taskx/jhacker/against-solution03
# now open some of the created files in your favorite editor:
netbeans --open taskx/jhacker/against-solution03/project.properties

Now adjust the content of the properties file:

# change definition of apitotest property to solution03:
apitotest=solution03
# you can also adjust the taskA and taskB variables to 
# reflect the days that you want to compete against
# for example if there is compatibility problem between
# task2 and task3, change them to:
taskA=${apifest}/task2
taskB=${apifest}/task3

Now you can open the project in the NetBeans IDE

netbeans --open taskx/jhacker/against-solution03/

or directly edit its jhacker/against-solution03/test/apifest/CurrencyTest.java file. The goal is to make this file compilable against api available in the version taskA. If you execute the project:

ant -f taskx/jhacker/against-solution03/build.xml run

or by pressing F6 in the NetBeans IDE, your test is compiled, executed against taskA and it has to succeed. If it does, the test is executed against taskB library. If it fails, you have demonstrated BackwardCompatibility problem and that is why the build succeeds. Make sure you open the Output Window to see the real resul! There is also the JUnit Result Window and it is not really helpful in the against project, but I do not know how to suppress its appearance. If the test succeeds with taskB library, the sources of your test are compiled once again against taskB library. This can fail, if there are source incompatibilities. Failure means your success, as you have demonstrated an incompatibility! To see result of these steps in action, look at my attack against solution02 (I can show it as it did not advanced into this final task and you cannot be awarded with points by finding problems in it). If you managed to attack one solution, perfect, you can repeat these steps for another one.

The rules for writing compatibility tests are similar to API Fest One - e.g. the less tricks you use the better. Where trick means more or less Java Permission. Do not try to use reflection that could obviously break each solution. Also do not use wildcard imports in source, that can easily break each solution as well. Do not put the code into the API package, that would allow you to use package private methods and would be unfair. Rules are simple: less tricks is better and I am the judge. Enjoy!

After you are done, please generate the diff using hg diff and submit your solutions by Sun, Oct 26, 2008, morning of CET to our mailing list. Possibly you can ZIP your sources and send them to us too. As soon as we process your submissions, I'll write an APIFest08 report and announce winners. Also I will prepare TheAPIBook for the winner.

--JaroslavTulach 06:03, 18 October 2008 (UTC)

APIFest08 Task 4 Necessary to Choose the Best API Designer

It is unbelievable! We are approaching task4 of APIFest08 and we still have eight participants who play with us! Moreover the competition is still not decided, as far as I can tell. Today I spent few hours looking for BackwardCompatibility problems in provided solutions and I still have not managed to break three of them! It is not that surprising as some of the competitors follow advices of TheAPIBook. For example I've seen APIDesignPatterns:ResponseReply being used. Guys, how can I find a quest for you if you know all the good tricks? Anyway this means we have to go on, as I have only two books to give to winners!

That is why let me ask call round4: Please integrate with dates. Keep history of conversions, allow queries in historical data, etc. Please see Task4Test.java with the actual quests.

Locate your solution among existing task4 directory. There shall already be Task4Test.java file along your Task1Test.java, Task2Test.java and Task3Test.java. Enhance your API, show its usage in the Task4Test.java. Remove the conditional if failing statements.

After you are done, please generate a diff. The best way is to use Mercurial:

# create the repository
hg clone http://source.apidesign.org/hg/apifest08/
# or update it
hg pull; hg update
# then do your modifications
# ...
# do not forget to add newly created files
hg add task4/solutionXY
# and finally produce a diff
hg diff

you can obtain the diff in other ways, potentially you can send us to our mailing list the whole ZIP file, but diffs are preferred.

Please submit your solutions by Thu, Oct 16, 2008, morning of CET. I guess this is the last coding round. On Saturday you will start hacking solutions provided by others!

--JaroslavTulach 22:17, 11 October 2008 (UTC)

Define "Friday Morning"

When I was defining the quest of APIFest08:Task3 I needed to set a deadline. However as the APIFest08 is not competition for millions of bucks, just for TheAPIBook, I did not feel I need to be exact enough and I defined the deadline as Fri, Oct 10, 2008, morning of CET. This is the reaction that I got from one of the participants:

I really like the precision you use in specifying the deadlines!
I will choose to interpret "Fri, Oct 10, 2008, morning of CET" as 
the time when  the first ray of the rising sun can be seen from 
the train I'll be taking to commute to Prague unless the window 
is too dirty, is that o.k.? :-)

Cute and OK. Of course only under the assumption that you do your best to clean or at least open your window in case it is too dirty and that you are not referring to a window of an underground train.

--JaroslavTulach 07:53, 8 October 2008 (UTC)

APIFest08 task3 is here

The task3 of APIFest08 is here to tease you more, dear participants. Btw. great work on the previous tasks! It is really hard for me to come up with a task that will be unimplementable for you. I guess you all defend BackwardCompatibility of your solutions pretty well.

Let see what will happen during the round3. I have prepared the Task3Test.java for you. Please enhance your API to allow your API users to write online convertor that updates its exchange rates all the time. Please find the details of your quest inside of the Task3Test.java file.

Locate your solution among existing task3 directory. There shall already be Task3Test.java file along your Task1Test.java and Task2Test.java. Enhance your API, show its usage in the Task3Test.java.

After you are done, please generate a diff. The best way is to use Mercurial:

# create the repository
hg clone http://source.apidesign.org/hg/apifest08/
# or update it
hg pull; hg update
# then do your modifications
# ...
# do not forget to add newly created files
hg add task3/solutionXY
# and finally produce a diff
hg diff

you can obtain the diff in other ways, potentially you can send us to our mailing list the whole ZIP file, but diffs are preferred.

Please submit your solutions by Fri, Oct 10, 2008, morning of CET, so we can process your submission before weekend and think about more sophisticated ways to tease you. Good luck!

--JaroslavTulach 09:27, 7 October 2008 (UTC)

New Code for Food Picture

The spirit of HtmlForFood story lives on! Geertjan did a NetBeans platform training recently and it seems he learned new skills, which include ability to debug and generate code:

--JaroslavTulach 14:58, 6 October 2008 (UTC)

APIFest08 task2 is here

The task2 of APIFest08 is here. We have fourteen solutions that advanced to second round. Some of them did use their chance to get up to speed in APIFest08:Task1.5, some of them did not. The latter ones will be in tougher position, as the second round is just about to start.

You task #2 is to allow one convertor to hold multiple rates of multiple currencies. Also, create an API to allow composition of convertors. Here is the Task2Test.java file with detailed description of the quest. Locate your solution among existing task2 directory, copy the Task2Test.java file along your Task1Test.java. Enhance your API, show its usage in the Task2Test.java.

After you are done, please generate a diff. The best way is to use Mercurial:

# create the repository
hg clone http://source.apidesign.org/hg/apifest08/
# or update it
hg pull; hg update
# copy the task 2 file
hg copy currency/test/org/apidesign/apifest08/test/Task2Test.java task2/solutionXY/test/org/apidesign/apifest08/test/Task2Test.java
# then do your modifications
# ...
# and finally produce a diff
hg diff

you can obtain the diff in other ways, potentially you can send us to our mailing list the whole ZIP file, but we want to have the right to process diffs first, as that is simpler for us.

Please submit your solutions by Sat, Oct 4, 2008. Good luck, and do not forget to keep BackwardCompatibility!

--JaroslavTulach 11:50, 1 October 2008 (UTC)

APIFest08's task one and half

Thanks you all, dear twelve brave men for participating in APIFest08! I was really glad to see your submissions after the task 1. I really like the variety between your individual solutions.

However, I also have to apologize. I did try, to correctly specify the task 1 goals, however, looking at some of your solutions, I failed. Some of your APIs do not satisfy all the use cases that I had in my mind. That is my fault, I should have expressed myself clearly. Anyway it puts us into bad situation. Now you are not at the same starting position for the real APIFest08 game. That is why I have to, like a starter seeing a problem before 100m run, call off the ready state, and ask you to prepare once more. That is why I am calling round one and half. Please adjust your your solution according to additional tasks, described in Task1Test.java. There is proper description of the behaviour of the factory methods and two more tests. Please implement this in your solutions.

Please do it by Tue, Sep 30, 2008, noon. You do not need to retain any backward compatibility yet, however restrain yourself from doing too big changes to your APIs, they are all good, just satisfy the additional use cases, please.

Please accept my apology, and good luck!

--JaroslavTulach 18:24, 28 September 2008 (UTC)

Ezekiel 25:17

"The path of the righteous man is beset on all sides by the inequities of the selfish and the tyranny of evil men..."

At certain moment, some ideas get "indexed". Such ideas get a single name, single label and it is enough to say just that name and the right rings are going to bell in heads of all listeners. You do not need to repeat the whole joke, it may be enough to say just the name of the main character in it. You may not repeat the whole story, it is enough to say "life is like a box of chocolate, you never know what you gonna get" and it is clear what is the story about. Or, just refer to "Ezekiel 25:17" and you can bet that most of your listeners will know what you are referring to. These sentences became "indexes" for their whole stories.

The trap that every author of a book shall be aware to not fall into is to become a generator of indexes for his own books. This is inevitable, at the end the author spend last few months reading again and again the same book. Reading own sentences over and over, changing words to make them better, more expressive, more sharp and exact. It is natural that for the author to see nothing more real than the book and its content. It is easy to fall in the trap of believing that this is so also for every other human being one meets.

As a result authors sometimes use sentences like "should you read the xyz book, you would know that...". Or refer to their work using "I have described uvw in Chapter 33, please read it". This is explainable, yet very annoying. I've faced that behavior once and I was quite up set and I knew I should restrain from doing the same after publishing TheAPIBook. I knew that, but I could not stop myself from doing that! It was so tempting to refer to chapter 11, Runtime Aspects of APIs instead of explaining that getting ready for reentrant calls is important. It was so easy and tempting, yet it was also quite annoying for people around me. At least that is my guess from seeing their unusual reactions to my speech or email in not so recent weeks.

Please take this as my public apology for using Jarda 15:13 or Jarda 7:3, etc. "indexes". I could always understand how it feels to get such self-reference. Sorry for that and I promise not to use it anymore.

PS: In case of need refer to this text as Jarda 24:9.

<comments/>

--JaroslavTulach 19:43, 24 September 2008 (UTC)

API Fest '08

The APIFest08, a game to practice Practical API Design skills, is just starting. It is a contest primarily designed for members of Czech JUG, but we want to make it as open as possible. Play with us and celebrate 10th anniversary of first public NetBeans release.

--JaroslavTulach 09:31, 23 September 2008 (UTC)

And the Winner of the HtmlForFoodCompetition is ...

Let me announce the winner of the HtmlForFoodCompetition.

--JaroslavTulach 20:25, 8 September 2008 (UTC)

First Public Review of Practical API Design Book

There is a review of TheAPIBook! Geertjan had just sent me a link to the first public review of the TheAPIBook. I was a bit nervous to open the page. I was not sure whether to get ready for absolute criticism or words expressing usefulness of TheAPIBook. I guess that a review which says 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 can only be seen in positive light. Thanks for the nice review, Mike.

Now on to the critical comments. Yes, I know the first part of the book, the theory, maybe seen as something delaying the real pleasure - the practical code samples. In some sense it does, however I just felt that given the wide audience of readers (just to quote the reviewer 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), I felt the need to get everyone on the speed, clean up the terminology, make sure we understand each other. Maybe I was too careful, as RichUnger said: you do not need your readers to agree with you 100%, maybe 99% is enough. Well, I targeted for the 100%, and as a result, the book may be seen slow for those who are already on the same boat. Still, it has a lot of meat even for such readers, I guess.

The other interesting comment was about the subtitle: confessions. The comment is very likely true. I have to admit, especially after the confession I made at the end of Chapter 4, that I have never been to a confession. My understanding of that term is really vague. However, we needed the subtitle to stress, that the book is not opinion neutral, that it contains personal experiences, ideas, stories, etc. When Clay suggested to use confessions, I felt, yes, that is sort of what I am actually doing. Maybe this is not absolutely correct, but it helps set the right expectations up. At least I hope.

I really like Mike saying: 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. Yes, this is it! This is the reason why I wrote TheAPIBook. Software for 21st century needs to be modular, needs to be well evolved and I am glad that my book can contribute to that.

Thanks for such nice review and I am eagerly waiting to see more. Btw. if you ever feel you have a note to share about API Design, feel free to jump on the apidesign.org wiki.

--JaroslavTulach 19:42, 2 September 2008 (UTC)

Win the Practical API Design Book

As part of Chapter 1, The Art of Building Modern Software I wanted to demonstrate that the need for programmers is really big and that almost everyone who wants to get a job as a programmer may get it. For this I wanted to reuse a picture of a San Francisco homeless that is famous for wearing sign with "Will Code HTML for Food". However I could not do that, because the picture is of really low quality. That is why I needed a new re-take. We already have some, but still, I'd like us to start sharing! As sharing of pictures is sometimes easier than sharing of API Design ideas, please participate in a photo contest! Get a chance to win TheAPIBook by taking "Will Code HTML for Food" like picture and adding a reference to it to HtmlForFood by Aug 28, 2008! I am looking forward your submissions.

--JaroslavTulach 16:11, 14 August 2008 (UTC)

New LaF of apidesign.org

The websiste has new look and feel.

--JaroslavTulach 10:09, 4 August 2008 (UTC)

There is a Reason Why Every Book is Dedicated to Family

I've heard this sentence at the J1 this year and I cannot get it out of my mind. Yes, family plays a really big role in the life of a writer. So please let me thank to it as well to other friends.

--JaroslavTulach 19:00, 27 July 2008 (UTC)

Good Book Needs Good Reviewers

It is time to thank to all my reviewers as today I've found out that you can order my book on Amazon.com. Please look at my little ThanksReviewers to find out why to order my book. I believe that all reviewers really shape it to something worth reading. Thanks a lot.

--JaroslavTulach 19:44, 18 July 2008 (UTC)

Removing Fear of Writing Documentation

Heuréka! As I've just noted in a dedicated page describing chapter 16, Teamwork one GeertjanWielenga's fear has just been overcome!

--JaroslavTulach 16:05, 17 July 2008 (UTC)

Adventures with PHP and MediaWiki

During the last week, I was slightly playing with various enhancements to the content of the API Design wiki.

--JaroslavTulach 21:14, 6 July 2008 (UTC)

Book is never Written by a Single Person

The Practical API Design book has been sent for print over the last weekend. I take it as a good opportunity to say thanks to all the people who helped me write it. The first set of ThanksEveryone notes is now available and covers those who "manually" contributed. I still need to thank to all those support "units" around me - something left for next blog entry...

--JaroslavTulach 12:01, 23 June 2008 (UTC)

Entering the Blogosphere

I have created my blog, does it mean that I finally exist?

--JaroslavTulach 09:33, 15 June 2008 (UTC)