Blogs:JaroslavTulach:Theory

From APIDesign

Theory Thoughts

Fuck Your Language Up to Become a Better Programmer

Language that you speak and write defined what you can think and reason about. The worse language you can use the better programmer you are. Right?

--JaroslavTulach 13:02, 16 October 2013 (UTC)

Do You Know What a WeakReference Can Do to Your API?

References and WeakReferences play important role when designing an API contract or building a framework. Are you sure you use them properly? Read about problems we had when messing with WeakReferences in the Lookup API.

--JaroslavTulach 08:50, 11 October 2013 (UTC)

JDK8's Profiles in the Light of Harmony

A curious translator of my book asked me about project Harmony. That motivated me to sit down and write an incomplete and mostly wrong history of open source java implementations. While incomplete (for example it does not talk by whom Harmony was founded and why), it explains why JDK8 is/will be a huge step forward and what will be its most important feature. Btw. if you thought lamdas, you were wrong.

--JaroslavTulach 14:54, 12 August 2013 (UTC)

Cimrman's Planning

Short introduction to accurate, agile, modern, reliable, flexible, optimistic, forward looking, experience based, projective planning methodology.

--JaroslavTulach 15:10, 19 March 2013 (UTC)

Platón's Theory of Ideas for Developers

Those of you who heard about Platon in school probably also hard about his allegory of a cave (at least I did when I was at high school). It is not often easy to imagine what Platon meant by the cave, shadows, etc. Luckily (at least for developers who know what geometry is), there is a better explanation which which explains Platon's theory of ideas via geometry.

This geometric way of explaining [[ideas was much easier for me to swallow. That is why I decided to share it here.

--JaroslavTulach 08:45, 21 January 2013 (UTC)

On the fact that the Atlantic Ocean has two sides

Here are selected notes from my favorite write up by Edsger W. Dijkstra (the guy that invented semaphore). Few decades has passed since the initial publication and the difference between U.S. and Europe may not be as sharp anymore. Still, a lot of Dijkstra's comments apply - especially when it comes to the clash between programmers educated in soft vs. real science schools!

Btw. should this kind of analysis be found interesting, I can share another one: Why our U.S. friends can't read maps and are not aware of that. Just let me know if I should publish it.

--JaroslavTulach 11:56, 17 January 2013 (UTC)

Having a Hammer All Problems Look Like a Nail

A theoretical observation about a hammer with application to real world scenario as well as software user interface design.

--JaroslavTulach 13:37, 12 November 2012 (UTC)

TransitivityOfIncompatibleChange

A nice clash between real world and academic attempts to describe it can be seen on the case of TransitivityOfIncompatibleChange. While such transitivity is an easy to grasp concept, it is too simplistic and often too hard to apply for the real world of software dependencies. It took me a while to understand its alternative, but now I think I see it.

Last week I had a presentation about the topic of NP-Complete problems in module dependencies at MatFyz and one of the questions was: Why am I not using TransitivityOfIncompatibleChange in case of repositories with RangeDependencies? Well, I don't as it does not have a clear meaning. But the question forced me to sit and write the answer down.

Hopefully not only MatFyz guys find the essay useful.

--JaroslavTulach 02:00, 7 November 2012 (UTC)

Is Java a Language or a Framework?

Just a few thoughts about the difference between language and a framework (plus a wish how Java should evolve).

--JaroslavTulach 09:06, 18 October 2012 (UTC)

20 API Paradoxes Published!

Today I am ready to announce great news. My new book about 20 API Paradoxes is now publicly available. I'd like to thank everyone who helped me get it to e-readers all over the globe. Jeff corrected my English and made the structure of the book more consistent. Clay stopped me when I wanted to expand the scope and delay the publication. And, most importantly, Clay is responsible for this fantastic cover:

I asked Clay to select cover that would somehow reflect my relation with my home and I am glad he decided to use painting of Josef Lada - a painter of my childhood.

I hope you like the cover too. And not only that, I hope you'll like the content as well. Buy & enjoy!

--JaroslavTulach 18:11, 11 October 2012 (UTC)

100th Monkey Principle. Multicasting in a Nature?

James Borowski on 100th Monkey principle:

Found reading some stuff on your site really interesting. I have not finished reading yet, so, forgive me if you already know this, but I was reading the article DiamondsVsStars and wondered as I read your comments regarding the "something in the air" as people around the world all discover something at the same time, if you were aware of the 100th Monkey principle?

There are different versions of the tale, but essentially, there was an island with a load of monkeys that learnt a trait one at a time of how to knock nuts with a rock to get inside them (other versions of the story are about learning to wash them, but the principle is the same). It took a while for monkeys to copy each other, one at a time, and the speed of uptake was essentially linear and at a fixed rate until they reached the 100th Monkey. At this point, every monkey on the island, and every monkey on the three neighbouring islands all started the same trait, almost instantly. The point is: A species appears to be connected at some vibrational level to the extent that they share certain thought processes/notions. There is a tipping point (apparently this is the square route of 1% of the population pool / or 100 monkeys ) where once reached, this information is availiable to all. Almost as if an entire species are listening on the same multicast address.

Anyway, hope you find as interesting as I found your stuff. For more info see 100th Monkey at wikipedia.

Thanks, for sharing this observation, James!

--JaroslavTulach 19:29, 8 August 2012 (UTC)

How Strict a Backward Compatibility Should Be?

Here are some thoughts on the difference between 100% BackwardCompatibility and their slightly more practical variants.

--JaroslavTulach 12:13, 31 July 2012 (UTC)

Dependencies Between Jigsaw Modules Made Easy!

Those who observe my blog may remember that I have an obsession. I am trying to understand module versioning and dependencies between modules. Recently I was playing with JigsawServices:

module M1 {
  requires service S;
}

The above concept is essentially NP-Complete as one may have choices from multiple modules providing implementation of the service and selecting the right one is NP-hard as explained in this example.

But I think I have found an acceptable solution. Today I will have a presentation about it (here are the slides). Wish me luck!

--JaroslavTulach 13:56, 24 July 2012 (UTC)

JavaFX + Swing: Together at last!

I am proud to announce that the mutual JavaFX and Swing interoperability has been greatly simplified. No need for massive amount of asynchronous Runnables! Your Swing code can directly talk to JavaFX data structures and your JavaFX code can manipulate with Swing objects. This is a small change, but huge step forward for Swing+JavaFX interoperability!

A related quiz: When your code runs, can it find a difference between threads it is executed in? My guess is that it cannot!

--JaroslavTulach 10:35, 23 May 2012 (UTC)

An API Proximity. Are You Close Friend with Your API?

How close are you to the API that you use? Are you friends? Do you hate each other? Have you memorize the API? Can you debug it? Is your API a clueless blackbox for you? Are you a calling client? Do you implement and provide some of the API concepts? Do you think I am asking silly questions?

It seems that proximity is one of the best ways to classify libraries into categories. So far I managed to recognize Zero to Many, One to Many, Few to Many and Many to Many proximity categories. They seem to directly influence the APIDesignPatterns one should use when designing such libraries. As such, when you are about to design your library, think a bit about the proximity you want to have with your clients and providers.

Btw. Most of NetBeans libraries is using the Many to Many proximity. I'll be more than glad if you decide to stick with our most favourite proximity style as well.

--JaroslavTulach 19:56, 12 May 2012 (UTC)

RangeDependencies May not Be Root of All Evil! But OSGi's High Shot Missed the Sweet Spot.

Most recent work on understanding range dependencies in modular systems seems to reveal that all the flaws associated with RangeDependencies (e.g. resolving module dependencies being an NP-Complete problem) can in fact be eliminated by so called complete repositories. Looks like it is time when I should apologize to poor RangeDependencies - it is not your fault, it is the way people use you that is causing problems.

Should I also apologize to OSGi? No, it is probably too early. we need to wait until complete repositories are adopted by that system. Until that happens I can still claim that OSGi's high shot missed the sweet spot!

--JaroslavTulach 10:33, 9 January 2012 (UTC)

Defending OSGi

My recent post about OSGi deficiencies generated some interesting comments and observations which seem worth to be shared. Thanks Mirko for stopping by and leaving your long answer.

I should probably mention that my talk Experiences from Building the Fastest OSGi Container on the Planet has been accepted for March 2012 OSGiCon - thus dear OSGi fans, I may be available for face to face exchange of arguments.

--JaroslavTulach 08:50, 25 November 2011 (UTC)

OSGi is Just Weird

Last week I submitted a paper to OSGiCon 2012. I'd like it to be accepted as I'd like to meet the Mylyn guys there. To attract a bit of attention to it I've decided to be a bit controversial:

OSGi is flexible, but not logical. OSGi is not well thought out. OSGi is over designed. Read more to understand why.

In case the previous ramblings would not guarantee me the invitation for OSGiCon, I can also be nice and say: OSGi is good for interoperability. Can my paper be accepted now?

--JaroslavTulach 15:23, 13 November 2011 (UTC)

Less is More: Erasure of Generic Types in Java

People like to complain about erasure of the generic type information during runtime. Yes, the lack of introspection is unfortunate. Since JDK 1.1 people got used to inspecting and reflecting almost anything. The fact that information about generics is erased provokes them.

However not everything is so bad. The erasure of the type information has benefits. For example we all know that covariance and contravariance is not very useful when designing APIs in Java, right? However due to erasure of the proper type information, there are situations when one can rely on it.

The less type info due to erasure allows us to achieve more!

--JaroslavTulach 18:05, 19 October 2011 (UTC)

Intelligent design or Evolution?

Are you fan of intelligent design or evolution? None, or you don't care? If you are designing APIs, then you should! Because intelligent design plays a central role in life of software architects. Your attitude towards it predefines how good architect you can be!

--JaroslavTulach 11:55, 25 July 2011 (UTC)

Is Java an Object Oriented System?

Few years ago I was chatting about Smalltalk with Peter Ahé (originally JavaC maintainer). We laughed at ridiculous classical Smalltalk coding practices, but then realized that to some extent similar style was used when designing Java as well. Peter even said that Java is not object oriented language but yaady-yaady-da oriented language. I no longer remember what exactly Peter called Java, but maybe you can read our Smalltalk objections and help find me the right name.

You are welcomed to comment!

--JaroslavTulach 14:58, 15 July 2011 (UTC)

Is God A Computer Scientist?

Last week I finished reading of the Is God A Mathematician? book and I can't prevent myself from recommending it by all means! My own book about API design uses various parables with the history of discovering the laws of real world. I used one very nice Czech book as an inspiration for these philosophical parts and I was always very sad that I cannot give my readers a chance to read it, as it was not translated to English. The Is God A Mathematician? book is a very good substitute.

If you want deeper insight into the "battle" between rationalism and empiricism, Is God A Mathematician? is a perfect book to start with. It does not cover everything that I'd like to be covered, but never mind, it is still quite a good book. Plus I have enumerated the omissions on my review page, including few notes about computer science.

--JaroslavTulach 20:16, 7 June 2011 (UTC)

Disassemble Your Types!

AssemblableTypes are your friend while modularizing your APIs. With their help you can make sure you disassemble your monolithic system into flexible and independent parts that smoothly assemble together when used by your API users.

--JaroslavTulach 17:08, 14 May 2011 (UTC)

Beginner's Guide to Modularity for DI Fans

Do you use Dependency Injection and are you curious about concepts of modularity? Then you can use this little guide explaining how certain concepts in Dependency Injection map to concepts in modular world.

--JaroslavTulach 16:49, 9 February 2011 (UTC)

Transactional Memory

TransactionalMemory is an attempt to bring the power of databases to general purpose programming languages. wikipedia:Transactional Memory should be the ultimate source of information, however it seems that much better understanding of TransactionalMemory can be obtained by reading follwing practitioner's report. Joe Duffy's text is worth reading - it shows why weak TransactionalMemory cannot work. In the process of showing that it describes the gory details that remain unnoticed in the general overview at wikipedia:Transactional Memory.

As far as I can tell Joe's write up is one of the best texts on internet I have read in months. It is deep, detailed, informative, entertaining and contains pieces of wisdom you don't want to miss. Like the "these kinds of moments make me a believer in formal computer science" acknowledgement.

A more meta-level thought: Joe's text shows why it is important to properly document failures. Why it is important to describe roads that lead nowhere. As Jára Cimrman says: Should not we value the person who tried to blow a cigarette smoke into watter to find out that this process does not produce gold? Thanks Joe for showing us that (weak) TransactionalMemory does not help to build reliable programming environment.

--JaroslavTulach 11:33, 2 December 2010 (UTC)

Excel in Designing DSLs for Excel People

Do you unit test your Excel formulas? Is that even possible? My new post is not going to teach excel users new tricks, but it may help you to excel in designing domain specific languages. Either external or embedded (into Java or Excel ;-).

--JaroslavTulach 21:53, 27 October 2010 (UTC)

"Five" Principles of Modularity

Here is quite nice summary describing the content of our yesterday presentation about Patterns for Modularity written by Roger Rached. I really enjoyed the talk and I'd like to thank everyone for stopping by.

--JaroslavTulach 01:09, 23 September 2010 (UTC)

Why SQL is not Ready for Internet Age?

Time to finish my SQL story. Today has been my last day in Sun. Tomorrow I'll sit at the same office and chair, but I'll be Oracle employee. Before that happens I can enjoy for the last time complete cluelessness about SQL. So here is it: follow this link to learn why SQL is not ready for internet age.

--JaroslavTulach 20:23, 31 August 2010 (UTC)

A Brief, Incomplete, and Mostly Wrong History of SQL

The SQL story was in my mind for a while. I was lazy to write it down, I just talked about it with various persons directly. But I can't wait any longer. Since Sep 1, 2010 I will start working for a major SQL database vendor and as such I should publish my SQL essays as soon as possible. Later it might contradict opinion of my employer. Learn about the alternative view of SQL history now!

--JaroslavTulach 09:53, 23 August 2010 (UTC) .

Are You Waiting for Your Application to Launch?

I am not sure what is your experience, but fast Startup is one of the important things netbeans:performance team focuses on. Did you find yourself having coffee break while waiting for your application to start? Then, you probably care. However not every kind of startup is similarly important. As such I have written little classification or startups. Walk through various startup types here.

--JaroslavTulach 05:46, 22 July 2010 (UTC)

Choose Your Dependencies Wisely!

I've just seen following quote in my mailbox: 'perhaps NetBeans is easiest to build plugin for...' (read: easier than other IDEs).

Well, the mileage may vary. However if you want (or even have people with knowledge of) 'standard' modularity and standard UI toolkit, then NetBeans Platform 6.9 is the easiest way to merge these two. We support Swing for ages and dedicated last nine months to interoperability with OSGi. Some even say it is easier to use Equinox with NetBeans IDE 6.9 than with Eclipse IDE.

I'll continue to investigate various interoperability options as part of my daily job. At the end it should not matter whether you code for Eclipse or NetBeans, but whether you have the right dependencies (read: no SWT, bunch of Swing and don't forget Lookup ;-). This is another sign that (when there is a common ground - a lingua franca - e.g. common module system for Java) interoperability will be easier than ever. Building applications will be like composing them from Lego bricks. There is only one prerequisite:

Choose your dependencies wisely!

--JaroslavTulach 08:11, 19 May 2010 (UTC)

Simplest Teleinterface

New Teleinterface has just been discovered! I was reading through my older posts today and I realized that MagicalStrings are in fact a form of Teleinterface.

--JaroslavTulach 10:11, 9 May 2010 (UTC)

Blame Your Architect!

As a continuation of my sporadic thoughts about MetaDesign I decided to look closer to the topic of responsibility today. To introduce the topic let me ask. What is more effective: if one architect does its job correctly or if thousands of users adjust to poor design? Find the the answer and instructions for proper use of your trashcan here!

--JaroslavTulach 07:44, 25 April 2010 (UTC)

Is OSGi Secret Society Ruling the World by Using Magical Buzzwords?

Do you know how to build a secret society? Use MagicalStrings! Recently my OSGi adventures and generous help of Tom Watson resulted in two things: I made Netigso more efficient. I realized that any API that uses strings can be made quite cryptic! Learn more about my inquiry...

--JaroslavTulach 20:15, 8 April 2010 (UTC)

Ever met an architect?

Is there anything like universal architecture rules? For a while I am seeking for ones and today it is the right time to share my findings. They are not complete, but join me with your comments on this discovery journey.

--JaroslavTulach 19:29, 10 March 2010 (UTC)

Know it Better!

Based on classical SuperVsInner example I'd like to formulate one important advice to follow when designing an API.

--JaroslavTulach 12:40, 24 February 2010 (UTC)

What is a chance?

What is a chance?

--JaroslavTulach 19:11, 17 February 2010 (UTC)

History Repeats in Cycles

Let me quote Tim and Andreas conversation about Ruby. Is every human activity destined to repeat what has already been invented? Repeat on a new, advanced level, so we can not only repeat old mistakes, but also add new ones?

--JaroslavTulach 05:23, 28 January 2010 (UTC)

Is Paradox unnatural?

Do you like paradoxes? Do you seek for them? Do you find them strange? Here is my little explanation why this is very natural, very human.

--JaroslavTulach 09:57, 19 January 2010 (UTC)

Quiz: Name the First OOP Language!

Do you know what was the first OOP language? I thought I knew - till yesterday when I read great essay about OOP. Enlighten yourself, read it too and learn name of the grandfather of all OOP languages!

--JaroslavTulach 08:20, 3 November 2009 (UTC)

Retarded Swing Programmer. Was: AWT Dispatch Thread...

I have to defend myself. I have received a lot of comments in response to my recent essay about use of AWT Dispatch Thread. Especially this one: Why was the event display thread used for non-painting computation in the first place? It's Swing 101 to not have long delays on the EDT...it's covered in any book on Swing as well. made me feel retarded for a while. But I am not bad (Swing) programmer. Thus I started to seek deeply in my soul and I have an explanation why some think we are doing things in wrong way, while we don't: It is because of DCI's specifics!

--JaroslavTulach 20:42, 30 October 2009 (UTC)

AWT Dispatch Thread Shall be Used Only for Painting!

Here is a little essay building up on adventures of this week and explaining the difference between our attitude towards rationalism and empiricism.

--JaroslavTulach 14:32, 23 October 2009 (UTC)

OSGi: Too Much Love will Kill You

Recently I was thinking about the way RangeDependencies are specified in OSGi and I was trying to find reasons why that is wrong and inside out. I don't think I succeeded yet, but I can at least show that with RangeDependencies one increases the risk of running into NP-Complete problems. RangeDependencies give you so much lovely power, that they somehow need to strike back and hurt you. Get ready for that!

--JaroslavTulach 19:53, 18 October 2009 (UTC)

Quiz: Who invented Convention over Configuration?

Do you know who invented Convention over Configuration paradigm? Me!? No, I am joking. But today I wanted to write a blog about one API Design Anti Pattern and surprisingly I realized that Convention over Configuration hype started by modern frameworks was in fact outrun by one core Java framework. Or do you know about older example of Convention over Configuration in Java? C? Fortran?

--JaroslavTulach 12:16, 20 September 2009 (UTC)

Is Maven Over Abstracted?

Not really. It is just not properly documented. I'd like to thank you all for your feedback on my recent post about Maven. I have successfully used the assembly plugin to create ZIP containing all my application JARs. This time I'd like to point out why I failed to do so without your help before.

--JaroslavTulach 09:14, 15 September 2009 (UTC)

Can Math Save Your Life? Sure, by eliminating NP-Complete Problem!

New proof is here!

The LibraryReExportIsNPComplete outlined the problem one has to face when practicing DistributedDevelopment. The page also proved that in its global scope the problem is NP-Complete with all its implications.

Surprisingly there seems to be an easy cure that eliminates the NP-Complete nature of the library re-export. Visit LibraryWithoutImplicitExportIsPolynomial to learn about complete repositories.

--JaroslavTulach 08:46, 2 September 2009 (UTC)

Imagine Living without Compatibility!

BackwardCompatibility is the only weapon we have against the madness of wikipedia::NP-Complete problems. Unless you want to turn your developers and application assemblers into highly performant NP problem solvers, learn how to achieve BackwardCompatibility.

--JaroslavTulach 20:46, 27 August 2009 (UTC)

Math that Affects Your Life. Learn to Avoid NP-complete Problems!

Hi all mathematicians out there! At least I hope there is someone with a little bit of math background among people reading this blog. I have a proof of existence of a new NP-Complete problem. First of all I need someone to look at it and tell me if it is correct. I believe the idea is fine, I am not sure if the proof itself is technically correct.

Hi the rest of us! For those who don't want to bother with complexity theory and rather stick with their keyboards or planning sheets, there is also a summary. Look at it and learn why a little bit of math can be good for your own design skills.

--JaroslavTulach 07:52, 25 August 2009 (UTC)

Changing Rules of the Game

When facing a problem, what can you do? Either seek a solution or redefine the problem. If you have power to change the rules of the game, then all problems become immediately much simpler. See this general principle in action during modularization of the Java SE.

--JaroslavTulach 05:49, 25 June 2009 (UTC)

False Expectations

Are you about to modularize your API? Do you understand what such step can bring you? Good. However check this note to also understand what it cannot help with...

--JaroslavTulach 14:57, 16 June 2009 (UTC)

Close Proximity of API-less APIs

Can you imagine world without APIs? I can now...

--JaroslavTulach 21:27, 11 June 2009 (UTC)

Hail to Modularity!

I've moved the modular programming manifesto into wiki. Will it stimulate readers to fix it and make it more up-to-date?

--JaroslavTulach 13:26, 22 May 2009 (UTC)

A Brief, Incomplete, and Mostly Wrong History of Programming Languages

A short look at history can quickly explain all our sufferings. I did such excursion in Chapter 1. The need for Cluelessness is shown there by describing history of computer languages and their oscillation between Rationalism and Empiricism resulting in more easy to use languages (e.g. for dummies) that produce programs requiring gigabytes of memory, tons of CPU time and sometimes enormous amount of virtualization to execute.

I believed my explanation was at least a bit entertaining, but it is definitely nothing compared to A Brief, Incomplete, and Mostly Wrong History of Programming Languages. Give it a try and read it! Very entertaining and in my opinion showing the incorrigible mankind's desire for cluelessness too.

--JaroslavTulach 17:14, 15 May 2009 (UTC)

Feeling Independent?

Most of our programs don't live in a vacuum. They require some supporting environment in order to work. One might think that such dependencies on surrounding are unified for whole lifecycle of a library. That would be false assumption. As the following note discusses there seem to be many TypesOfDependencies.

--JaroslavTulach 16:47, 23 February 2009 (UTC)

How current can you be? Not much, that's certain!

Looks like the Practical API Design book has a new reader. Welcome! Moreover David is not an ordinary reader. He is not afraid to ask questions. Perfect! Thanks for your interesting question and please check my answer.

--JaroslavTulach 21:09, 6 February 2009 (UTC)

Just Three Kinds of BackwardCompatibility?

Finally I finished the online page describing what it is BackwardCompatibility. It defines three different kinds: source, binary and functional and I am curios to know: Is that all? Or can you think about other types of compatibility?

--JaroslavTulach 15:30, 21 December 2008 (UTC)

Declarative Registrations

I see the year 2009 as the year of annotations. At least for the NetBeans project - we are about to use them much more frequently than we did so far. That is why I cannot stop thinking about various ways of using Declarative Programming. As a result, there will be more blog posts about such programming style. Here is one: my little explanation why less is better when using the Declarative Programming registrations.

--JaroslavTulach 14:43, 5 December 2008 (UTC)

3 Sides to Every API

3 Sides to Every API is my reaction to excellent Beauty matters summary provided PetrHejl. It is my attempt to agree with him, while defending TheAPIBook's often proposition that beauty does not matter...

--JaroslavTulach 21:37, 24 November 2008 (UTC)

Beauty Matters

J. Tulach in his Practical API Design book claims that beauty is not the most important requirement when you design your API. Because he is repeating this multiple times at various places I got the bad feeling that this could be easily misunderstood. Let me clarify...

--PetrHejl 14:38, 11 November 2008 (UTC)

What Makes a Technology good?

Dear API users, can you help me define term Good Technology? What makes a technology good, useful? How do you evaluate quality of the APIs you use? I've just written few thoughts about this topic down, however I'll be glad to hear your opinion. Is NetBeans platform Good Technology or bad?

--JaroslavTulach 18:26, 3 November 2008 (UTC)

The Better Compiler the Worse API!?

Today I am ready to announce a really nice addition to the collection of weird examples of APITypes. Did you ever suffered with compiler optimizations? Did you ever thought about them as being an example of an API?

--JaroslavTulach 18:57, 16 October 2008 (UTC)

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)

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 BackwardCompatibility. 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)

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)

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)

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)

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)

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)

Dependencies Are Important Type of API

New type of API has been discovered!

JaroslavTulach 07:05, 15 July 2008 (UTC)