Amoeba Model

From APIDesign

Revision as of 05:55, 20 October 2018

What does a "quality of a library" mean?

There are many possible answers to the question "when an application has good quality?". Depending on one's standpoint the application can be requested to have a slick UI, natural work flow, be acceptably fast, not crash from time to time, etc. These are all good expectations, and let's include them under one general category - specification. If we are good (UI) designers and if we can understand the user needs, then we can create a good specification, which describes how our application should look and behave.

Amoeba Model

The Amoeba Model is one way to imagine the relation between the specification, that is our expectations and the reality. Here is a picture showing our great vision:

Yes, the visions are always nice. However this does not mean that our users will be satisfied with the quality of what they really get. A good enough specification is just half of what they see. They also need good enough implementation. Any expectations we put into our application can or even are (in ideal state) expressed in our specification, but before they get to the user they have to be implemented in code and it is very likely that the code will not follow the specification fully. There will always be differences between the code and the specification.

The amount of the differences between our code and our specification is the measurement of quality. If the final system is not doing what we originally intended it to do, then it is not good enough. Its quality or maybe better term is our confidence in it is lowered with every difference from the expected behaviour.

Sometimes the application does not do what we expect it to do, sometimes it does more. Both situations are dangerous, but only one of them is easy to find. One can read through the spec and test (manually, automatically) if everything that is requested is really implemented. So by carefully testing for the expected features of the library, one can minimize the places where the code offers less than expected. But even this has its limits:

Over the time, with new and new releases, regressions occur. The functionality of the code is changing, it starts to do new things and alas, it also stops to do what it used. Of course one can execute the manual test procedures once more with every release, but that is first of all very expensive as people have to try all specified features from all previous releases, and the accuracy of such findings often is not good enough. As a result the shape of the application code is changing from release to release as real amoeba changes its shape over time. That is why this behaviour is called the Amoeba Model.

Minimizing Amoeba Effect

Clearly, the differences between the perfect vision and imperfect real estate are always going to exist. The goal of API designer is to minimize them, the less differences between them, the greater will be the chance that the API user and API designer are going to understand each other. As API designed is mostly about communication (see Chapter 2) it helps if the API designer and user talk the same language - for example they know and use the right APIDesignPatterns.

The other important direction to tackle the Amoeba Model differences, is to do testing. At least run some SignatureTests to guarantee Binary Compatibility and also have some automated tests to assert functional compatibility during runtime execution (more in Chapter 11).

First Amoeba Video

For a while I am publishing API Design Tips on this website, but today I felt a bit sorry about having just the audio, no appropriate video. I know there are sound visualizers like goom, but still I wanted to do something related to TheAPIBook. What is that? Well, one of the suitable visualizations could be based on the Amoeba Model. Nervous, shaking amoeba could be good visualization for a sound.

Thus I created a life Java component that can shakes like amoeba (as drawn by HP guys). It took a while, but Java2D is powerful and as soon as one learns to provide proper coordinates to Bézier curves, one can get really nice, rounded shape. Enjoy the Media:Apitip06-year-of-annotations.mp3 with video:

Then it is just a matter of converting such shape from Java's Graphics2D into a movie. For a while I was struggling to find the simplest way to do it, but at the end I found nice Java application/library that knows how to store sequences of BufferedImages into .avi movie. This clearly shows how important good libraries are. I am completely clueless about the .avi format, yet it was just a matter of few lines of code to produce it.