Robert C. Martin proposed the idea that for well designed software there should be a specific relationship between two package measures: the abstractness of a package, which shall express the portion of contained abstract types, and its stability, which indicates whether the package is mainly used by other artifacts (stable) or if it mainly depends on other artifacts (instable).

The desired relationship is captured in the Stable Abstractions Principle: A package should be as abstract as it is stable.

By sticking to this principle we avoid getting packages which are used heavily by the rest of the application and which, at the same time, have a low degree of abstraction. Such packages are a constant source of trouble, since they are hard to change or extend.

Main Sequence

Let's get a little bit more detailed now.

• The Abstractness A for package P is calculated as the ratio of the number of abstract types contained in P to the total number of types in P. Thus, the resulting values range from zero (only concrete classes) to one (only interfaces and abstract classes).
• The Instability I for package P is calculated as the ratio between the number of classes outside P required by P and the total number of classes outside P related to P. As above, the resulting values range from zero (only incoming dependencies) to one (only outgoing dependencies).

What was this good for? Well, given these two metrics, the Abstractness and the Instability, we can place every package of our application in a diagram which shows the unit square with the Abstractness on the horizontal axis and the Instability on the vertical axis.

Furthermore, we can restate the Stable Abstractions Principle in graphical terms: packages should not lie too far away from the falling diagonal of the diagram, which is called the Main Sequence. This means that packages with a low degree of Instability should have a high degree of Abstractness and vice versa.

The packages which reside in the corners apart from the Main Sequence show specific problems: the lower left corner is called the Zone Of Pain, since its inhabitants are stable and concrete, thereby contravening the Stable Abstractions Principle, whereas the upper right corner is called the Zone Of Uselessness containing packages that are highly abstract and that nobody depends upon. These are the two areas of the diagram which should be avoided.

Distance

So now we've got everything together to define the Distance D, which indicates how far a package is away from the Main Sequence:

D = A + I – 1

Calyculating the Distance this way, we get values between -1 and 1. A zero value means the package lies exactly on the Main Sequence, the sign indicates if the package is located above or below the Main Sequence. A derived metric, the Absolute Distance (|D|), omits the sign, thereby allowing to compute meaningful average values for higher level artifacts.

STAN's Distance Chart shows you where your packages live, whether they are located near to the Main Sequence, as desired, or if they tend to drift to the bad corners. Every package is displayed by a bubble, the size of which is determined by the number of classes in the package. The color of the bubble reflects the rating of the package's Distance value, which is, as always, adjustable to your requirements.