Amoeba Model

From APIDesign

Current revision

What does a "quality of a library" mean?

There are many possible answers to the question When does an application have good quality? Depending on one's standpoint the application can be requested to have a slick UI with natural work flow. Others may ask for it be acceptably fast - e.g. have a good performance. Almost always we want the application to not crash too often. For some modularity and extensibility is the essential system feature. When talking about libraries/applications with an API it may be important to have good documentation. Externally facing systems are often requested to be secure.

All of the above are great features, but it should be pointed out that not all of them are really needed every time. Security is extremely important when writing an internet wide end point. On the other hand, nobody cares about security when writing a MapReduce script. User experience needs to be smooth for applications with UI, but it is completely unimportant for a Linux kernel module. The set of expectations is different for every project.

Let's include the expectations for a certain project into one general category - specification. Let's pretend for a moment the specification is well understood (written down, shared between project participants). That's usually distant, unachievable dream - there are many implicit expectations based on project context, but real architects, real UI designers, shall be able to prepare such specification. Thus let's assume a specification describing how our application should look and behave exists.

The 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.

The Quality Equation

 quality = specification Δ implementation

Minimizing the Amoeba Effect

Clearly, the differences between the perfect vision and imperfect real estate are always going to exist. The goal of an 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 design 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. Have some CodeCoverage with automated tests to assert functional compatibility during 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.