Blogs:JaroslavTulach:Theory

From APIDesign

Revision as of 10:11, 9 May 2010

Theory Thoughts

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)