Blogs

From APIDesign

The Theory | Practical Design | Daily Life | Jesse on Design | Andrei on Enums

1 Confessions of API Designers
2 Notes for blog writers

[edit] Confessions of API Designers

For a long time I was asked to create a blog and join the blogosphere. One my friend even told me, that people having no blog really do not exist. That is why, here is my blog to prove my existence. However, in the spirit of TheAPIBook, I'd like this to be place for cooperation. So, if you feel you have something to say about API design, and you are looking for a place to prove your own API and Blog existence, just tell me. You are more than welcomed to join!

[edit] Jaroslav Tulach's Theory Thoughts

[edit] More on Ruby, Gems and Modularity

The Ruby anonymous coward which brought duck-typing into attention of readers of this blog, added new comments to our discussion. The note presents Gems and I have to admit that by having Gems as standard packaging and dependency management tool, the Ruby gets far ahead standard offerings of Java. Of course unless you decide to use NetBeans runtime container or similar...

--JaroslavTulach 09:32, 30 September 2008 (UTC)

[edit] Are APIs like diamonds or like stars?

Is it uncommon that the same invention is discovered multiple times? Multiple times by different people? At the same time? It is indeed surprising to see something like that, however if you look back at the history of science, it is not that uncommon. I know that lightning rod has been independently invented by at least two people in the middle of 18th century. What was so special then that allowed such independent break-through?

For a centuries great mathematicians were troubled by Euclid's fifth postulate. It felt somewhat unnatural compared to the first four, the general expectation was that it is not necessary and it can be derived from the four others. Many tried, yet nobody succeeded. However, at the begging of 19th century things changed. Independently János Bolyai, Nikolaj Lobačevsky and maybe also Gauss discovered that fifth postulate is independent on the others. As such we can have geometries accepting and denying it and yet they'll make sense. Why at that time? Why three people at once?

There are many more cases that exhibit such coincidence. I do not think anyone has reasonable explanation for that, my personal feeling is that each era has something in the air that turns people's attention towards similar problems and tunes their mind to frequencies helping discover similar solutions.

I've been thinking about the laws of proper API design since 2001 and for a long time I believed that I am the only one who cares about such topic. I was pleasantly surprised during the Java One 2005 fully crowded BOF. However I still believed NetBeans is the only organization that does some research in this area. You can imagine how much I was surprised when I found out, at the end of 2005, that Josh Bloch had spent some time thinking about API design too. And that was not enough, my surprise even grew, when I found out that 80% of his observation in his presentation are similar to mine. There must have been something in the air, mustn't it?

As one comment stated: These things are a lot in Jaroslav Tulach's new book. Only real difference is that 'diamonds' above are 'stars' there. This comment brings us to the title of this post. Things looking similar at first sight may not be same underneath. At the end of 2005, most of the ideas were ready. They just waited for someone to put them into a book. When I finally began to write TheAPIBook, I was searching proper allegory to introduce the reader to the special context of API design. I knew the diamonds methaphor, but I could not use it, as I believe it is missing something important!

There is a significant difference between diamonds and stars. While diamonds are said to be forever, nobody considers stars eternal. As such the allegories are not the same. They are in fact quite different. If you get through the Practical API Design book to chapter 15 and chapter 19, you'll find out that if you have good support from runtime container, properly versioned APIs and you know how to allow co-existence of multiple versions of similar APIs, you can make your old APIs disappear, yet keep backward compatibility. Of course, this is not a common operation, just like stars do not burn out everyday. However, if you really need to, you can send your API (aka your star) towards a black hole and make it disappear there. Moreover, you can do it in a completely user driven way, where the speed of dying is driven by number of remaining users of the old API, e.g. observers of your star. This is all possible and the NetBeans project done that few times.

In short, although APIs look eternal, they are not forever, they are more like stars.

--JaroslavTulach 03:34, 26 September 2008 (UTC)

[edit] Can duck-typing help with API evolution?

I've just received a comment mentioning Ruby's duck-typing as a solution to evolution problem in API discussed herein earlier. Interesting food for thought! Thanks! However so far I have to admit that there is no obvious benefit, at least not in the particular case. Read more and feel free to comment...

--JaroslavTulach 15:54, 22 September 2008 (UTC)

[edit] getDate() method evolution thoughts by Tim Band

Imagine that you have a class with method getDate() which returns the date of creation of that object. Can you add setDate() in new version? Can that change be compatible? This is topic discussed recently by Tim Band at LtU discussion forums:

If the get_date function had a comment stating "Returns the date at which the object was created" then you have to update that comment -- and that semantic change to get_date is the break.

It is hard to think of a semantic meaning for a get_date function that covers the setting of an arbitrary date, so let's imagine that we want to add "refresh_date" and that the original documentation of get_date said "Returns some date between the creation of the object and the calling of the function", then adding refresh_date is OK.

If get_date is undocumented or ambiguously documented, you need some process to resolve this. At Symbian we have a board of beard-strokers (of whom I am an occaisional member) who deliberate on the difficult cases and inform the customers of our decisions, and get feedback on certain issues. This process is considered integral to our backwards compatibility promise.

It is tempting to dream of a world where a programming language or supporting infrastructure would free us of the compatibility burden, turning it into just another language feature. However, it is in the mucky world of semantics, where interfaces meet the world of human use and abuse where this stuff really matters. You can break compatibility if you know it won't matter (we once changed our formerly weird floating-point implementation to match IEEE with no-one even noticing), but you can't make some compatible changes (changing priorities of processes that have no stated dependency on each other is a classic).

Having said all that, there is much work to be done on merely keeping interfaces stable. You can get quite far just by assuming that the source interface (your class and function signatures in your .h files in C++) matches the semantics, and picking up incompatible changes to that over time (removal of functions for example) and alterations of the binary interface in relation to the source interface (adding a virtual function for example).

Of course, occasionally you must allow customers to override common sense; I'm sure many readers here are familiar with the story of Microsoft Windows' memory manager running in a different mode if it detected Sim City running -- this is always a risk and you have to be aware that you might be forced to retract changes in the face of politics.

I should probably stop now, although really I'm just getting started! Tim Band

--JaroslavTulach 07:32, 17 September 2008 (UTC)

[edit] Joel Neely on Enums in APIs

Today I found out that there is an interesting comment to the blog entry published by Andrei a week ago. Andrei shared with us few thoughts on the use of enums in API. Joel Neely noted that it all depends on how the enum is used in the API. I cannot do anything else than agree with his words, yes it depends on whether the enum is used covariantly or contravariantly. If the enum is used covariantly only, then extending it with new constant in new version of the API is OK.

The only problem is that as soon as you publish an enum, one can immediately write a switch statement over it. And the switch statement's behaviour is contravariant. That is no good news for the API writers and compatible extensibility of their enum based APIs...

--JaroslavTulach 21:22, 26 August 2008 (UTC)

[edit] Are there any Languages Ready for API Evolution?

When I was describing my API design adventures in TheAPIBook, I could not realize that many of these problems would not even appear if we had better languages, or systems more suitable for the DistributedDevelopment.

I may be wrong, but I do not know about any language that would support modularity. And here I mean not compilation piece by piece, but also modularity in time. Because that is the kind of modularity that is needed quite often during development of APIs for our libraries.

At one point of time we release a version of a library and distribute it to others by publishing it on the website. Now people unknown to us, distributed all around the world download it and use it. As a result, the amount of applications built on top of such library is increasing, which implies also that the amount of bugs and feature requests is growing too. After a while the time to release new version of the library comes. However what if the first version used to have a class:

public abstract class View {
  public abstract String getDisplayName();
}

What if one of the feature requests demands to add an HTML title to each view. Can we change the view class to following form:

public abstract class View {
  public abstract String getDisplayName();
  public abstract String getHTMLTitle();
}

Indeed, this cannot be done. Existing subclasses of View would no longer compile, because the change is not source compatible. Also, even if someone links already compiled subclass with the new version of the library, the Java virtual machine will complain and throw some kind of linkage error, as definition of an abstract super class method is missing.

I would love to see a language or system that would fail the compilation whenever I want to modify my already released classes in a style that could prevent some of their users to continue to use them in previously working way. This would be the real modularity, which is ready for changes in time. So far it seems to me that the current languages do not deal with changes in time really well. Just like Andrei described in his Enums in APIs blog, it seems that our languages do not think about the process of API evolution much and include constructs that one needs to avoid to make DistributedDevelopment possible.

Releasing new version of libraries with modified APIs is really common and our software engineering practices cannot live without it, yet it seems that there is no language in the world that would make this easy and clueless. Or am I wrong?

Also lively discussed at Lambda the Ultimate.

--JaroslavTulach 06:50, 24 August 2008 (UTC)

[edit] Visual Aspects of an API

The usual consensus is that visual aspects that are presented just to the end user are not part of API of some application. This is usually well justified and correct, except in some situations...

--JaroslavTulach 11:40, 11 August 2008 (UTC)

[edit] Dependencies Are Important Type of API

New type of API has been discovered!

JaroslavTulach 07:05, 15 July 2008 (UTC)

[edit] Jaroslav Tulach's Practical Design

[edit] Exceptions in API

Casper Bang asked following question about exceptions in API after reading the TheAPIBook:

I was curious as to know how come, in a book strictly about API design in Java, you do not mention exceptions (particular checked exceptions) and the role they play in documenting assertions vs. hampering versionability. Did you simply think this to be too controversial an issue I wonder?

Good question! Inspiring. Here are my current answers: exceptions in API.

--JaroslavTulach 21:37, 14 September 2008 (UTC)

[edit] Have You Ever Wondered?

Many people want to know, before they start to read a book, whether it can help them solve some problems they have faced. That is very likely reason why many books start with have you ever wondered sections. The Practical API Design book does not contain such section itself, however that in no way means that there it is not helping to solve problems! You can bet that there is a lot of useful advices! The book is a lab journal describing adventures of NetBeans project and as such, it is almost completely stuffed with problem solutions. Here is short online version of Have You Ever Wondered to demonstrate that. Visit the page and check yourself what problems can TheAPIBook solve for you!

--JaroslavTulach 20:42, 17 August 2008 (UTC)

[edit] Request/Response Pattern Revisited

Here is few additional thoughts about Request/Response which did not make it into TheAPIBook's explanation of Request/Response pattern.

--JaroslavTulach 21:02, 25 June 2008 (UTC)

[edit] Jaroslav Tulach's Daily Life Blog

[edit] 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)

[edit] 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)

[edit] 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)

[edit] 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.

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

[edit] 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)

[edit] 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?

As you may heard already in the podcast, the winners are cismet guys! Congratulation!

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

[edit] 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)

[edit] 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)

[edit] 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.

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

[edit] 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)

[edit] 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)

[edit] 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)

[edit] 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)

[edit] 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)

[edit] Entering the Blogosphere

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

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

[edit] Jesse Glick

[edit] Question on classes and interfaces

Someone asked: I guess that, roughly, a client API should use abstract classes while a support/provider API should use interfaces?

To which I responded...

--JesseGlick 09:33, 15 July 2008 (UTC)

[edit] Andrei Badea

[edit] Enums in APIs

An user of an enum might want to ensure he has processed all its fields. This can be problematic when the user doesn't own the enum, such as in an API.

--AndreiBadea 14:18, 16 July 2008 (UTC)

[edit] Notes for blog writers

The Blogs support on this site is using WikiArticleFeeds extension configured to recognize following tags:

<startFeed/>
==== Blog entry ====
 
Some introductory text with a [[link]] to your article.
Followed by your signature:
 
--~~~~
<endFeed/>

There is also MediaWiki's GeSHi extension installed. So in case you need to provide code snippet, use the source tag:

<source lang="java">
...
</source>

In case you are writing a blog entry where you expect lively discussion and participation from others, do not forget to end your page with:

<comments/>

That tag pre-creates a new and easy way to submit comments to your blog page.

Retrieved from "http://wiki.apidesign.org/wiki/Blogs"