Blogs:JaroslavTulach:Daily Life

From APIDesign

Daily Life Blog

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!

--85.160.165.140 14:17, 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 ...

The HtmlForFoodCompetition which we run in order to promote TheAPIBook and popularize its major concepts is running towards its end! I have already selected the winner using a complex mathematical operations with a huge contribution of pseudo randomized numbers. Please tune in the next NetBeans Podcast Episode 46 and hear the announcement yourself!

I can only say that the submissions we got were really great:

• Vincent Cantin was looking so desperately sad.
• cismet guys provided wide range of variations on the "code" topic.
• Tonni Epple draw a perfect caricature.
• Andre Pinto pictured himself with a beautiful selection of languages and "code" sentences.
• Full Movie was not really submitted for competition, however it is very nice exploration into everyday developers' pains.

Who will win TheAPIBook by providing the best Html For Food picture?

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

There was a lot of factors that influenced me last year, when I was searching for publisher of my book. However one of them must have been slickness of cover. I really like the black and yellow style of Apress books. I like it so much that I decided to make it the default Look and Feel of the apidesign.org website.

I'd started with MonoBook theme and modified it to be a bit darker. I do not code CSS for living, but CSS file editing support in NetBeans IDE is good, so it was quite entertaining experience. I am sure not everything is perfect, but I'll keep fixing problems as they appear. If you notice something ugly or broken, let me know.

<comments/>

--JaroslavTulach 10:16, 4 August 2008 (UTC) --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)