CSC/ECE 517 Fall 2007/wiki3 8 as

OO Package Design Principles

O-O design guru Bob Martin has developed a set of design principles that relate to packages (one level above the class-oriented strategies we consider in this course). Report on the

Reuse/Release Equivalency principle,

Common Closure principle,

Common Reuse principle,

Acyclic Dependencies principle,

Stable Dependencies principle, and

Stable Abstraction principle

Find the best descriptions and examples of each that you can find on the Web.

Packages

Robert C. Martin describes the term “Package” as “a logical grouping of declarations that can be imported into other programs”. Since packages serve as a container for a group of classes, those classes need to be partitioned based on some criteria and then allocate the partitioned classes to their appropriate packages. The relationship between those packages identifies a high level organization of the application. Martin has put together many design principles for guiding the creation, interrelationship and use of packages.
Three principles of Package Cohesion are –

Reuse/Release Equivalency principle

Common Closure principle

Common Reuse principle

Three principles of Package Coupling are –

Acyclic Dependencies principle

Stable Dependencies principle

Stable Abstraction principle

Package Cohesion Principles

Reuse/Release Equivalency principle

When developers reuse a class, it is a disadvantage when they have to recompile the code everytime there are changes done to the class. There should be a process of controlled release to enable maximum class reuse. The principle as stated by R.Martin in his article Granularity -

   “The Granule of Reuse is the granule of Release.
   Only components that are released through a tracking system can be effectively reused. 
   This granule is the package.”

The packages of a reusable component should be grouped based on the usage and not be based on common functionality or by any other arbitrary category. Usually most of the classes like the containers and iterators are usually grouped based on their collaboration with other library classes. Reusuability is an important principle of OOD since it helps to eliminate the creation of duplicate code in the system. If a class in the package is being reused, then all the classes in the package have to be reused. Whenever the packages are fixed for bugs or enhanced by the author, a new version of the package can be added to the system.

Example

If a payroll application is being used by many applications, then it should be a packaged into a single unit. Whenever a change is being made to any of the classes in the application, a revised version of the whole unit can be released. This helps the users of this application to keep track of the latest versions even if they are using only a particular function of the application.

Links

Principles of Object-Oriented Design- gives a brief explanation about Reuse/Release Equivalency principle on page 15. It describes how packages of reusable components have to be grouped to enable maximum reuse.
Reuse/Release Equivalency Principle- is a blog that explains the REP principle and also provides the reason why not individual reusable classes are being released.
OO Design Principles- page 54 of this document gives the requirements of a reusable software and provides summary of this principle.

Common Closure Principle

This principle ensures that classes within a released component share a common closure, i.e. if a class in a released package requires a change then all the classes in that package needs a change. The principle as stated by R. Martin in his article Granularity –

   “The classes in a package should be closed together against the same kinds of changes. 
   A change that affects a package affects all the classes in that package”

Maintainability is more imporant concept of OOD than Reusability. If two classes are either physically or conceptually tightly bound, that they change together, then it is more reasonable to use them in a single package. The advantage is that it minimizes the workload of releasing, revalidating and redistributing the software and the impact of change on the programmer. It restricts changes to a fewer packages and also reduces the frequency of package release.

Example

Since each class in the payroll application are dependent on one another, any changes made to one class reflects on the other and hence, they should be used together. If the classes are available on different packages, then it would be a difficulty in releasing the application. Each class that underwent a change should be put into a package and then released. By packaging the classes that change together, maintainability is a lot easier.

Links

Principles of Object-Oriented Design - gives a brief explanation about the common closure principle on page 19. It also compares reusability and maintainability by specifying when to use REP, CCP and CRP.
Common Closure Principle - is a blog by Abhijit Nadgouda which gives a brief introduction to the Common Closure Principle.
OO Design Principles & Metrics – defines the principle with a basic diagram as an example.

Common Reuse Principle

The principle is stated by R.Martin in his article Granularity as –

   “The classes in a package are reused together. 
   If you reuse one of the classes in a package, you reuse them all”

This principle helps to decide how the classes can be put into a package. If the classes are being reused together, then they should be put into a package. In his article, Martin gives a simple example of a container class and its associated iterators which can be put into a package since the classes are tightly coupled to each other and hence they have to be placed in a single package.

Example

A package for matrix calculations, should consist of only matrix functions and not the trigonometric functions. It makes the principle of reuse a lot easier.

Links

Common Reuse Principle - is a link to a blog that describes the necessity of the common reuse principle. It also states the principle and gives an example about a package of matrix calculations.
Principles of Object-Oriented Design - gives bulleted hint about the principle. It also gives the Façade pattern as an example of a common reuse in practice.

Package Coupling Principles

Acyclic Dependencies principle

This principle ensures that the packages are not indirectly dependent on it. Martin’s solution to this problem of dependency is to partition the development environment into releasable packages. The dependency problem can be solved by drawing the dependency graph structure of the packages by using the packages as nodes and directed dependency releationships as edges. Such a structure is called the Directed Graph. The principle in Martin’s article Granularity states the Acyclic Dependencies Principle as-

   "The Dependency Structure between packages must be a directed acyclic graph(DAG). 
   That is, there must be no cycles in the dependency structure”.

The article gives the effect of a cycle in a package dependency graph and explains how to break that cycle.
In C++, packages depend on on another by using #include in the header of a class, which is present in a different class. Such a dependency relationship between packages can be depicted by the diagram.

Example

Considering the package dependency graph displayed, we can see that there is a cycle in the dependency since the package MyDialogs has a dependency on MyApplication. For instance, if the developers of MyTasks want to make a release, then it must be compatible with Task, Database and MyDialogs. But with the cycle in place, Task has to compatible with MyApplication, TaskWindow and MessageWindow. In other words, Task is now dependent on all the packages in the system. Another reason is that if a unit test is to be done on any one of the package, it requires a complete build of all the packages since they are linked and have virtually become one large package.
This situation can be prevented by breaking the cycle. There are two options to break the cycle - Applying the Dependency Inversion Principle or Create a new package that depends on MyDialogs and MyApplication depend on. All the classes that depend on both the packages are moved to the new package.

Links

Principles of Package Design - describes how to apply ADP and break any cycles that appear in the dependency graph. Although there is not much information, it gives quick points on the principle.
OptimalAdvisor - is a static code analysis and refactoring tool and It can be used to indicate problems and solutions. The tool finds problems in dependency structure and suggests solutions to fix them by using the acyclic dependencies principle.

Stable Dependencies principle

In his article Stability Martin gives detailed explanation and examples about stability and dependency. He stresses on the stability property of classes, as stables classes are both Independent and Responsible. The principle is states as –

   “The dependencies between packages in a design should be in the direction of the stability of the packages. 
   A package should only depend upon packages that are more stable that it is.”

The article also explains about Stability Metrics which is used to measure the stability of the package. The Instability(I) metric can be calculated using the afferent and efferent couplings and has a range [0,1]. When the I metric is 1, it means that this package depends on other packages but no other package depend on it. Such a package is very instable because there is no reason for the package to change due to non availability of dependents, and it changes only when the package it depends on undergoes a change. When the I metric is zero, there are packages depending on this package but it is not dependent on other packages. Such a class is responsible and independent. The principle says that the I metric of the package should be greater than the I metric of all the packages it depends on.

It also mentions that not all packages can be maximally stable, since it would render the system unchangeable.

Example

Instead of having separate classes like FileLogger or DBLogger, there can be a single interface called Logger

Links

OO Design Principles & Metrics– gives reasoning why stable dependencies principle should be applied on the package. It also explains the stability metrics with an example.

Stable Abstractions principle

This principle states that a stable package should be abstract too, so that it gives an opportunity to be extended. The article Stability by Martin gives the best description and example of the principle. It is stated as –

   “Packages that are maximally stable should be maximally abstract. 
   Instable packages should be concrete. 
   The abstraction of a package should be in proportion to its stability.”

It also gives a way to measure the abstractness of a package. The mathematical explanation helps to decide if a package is abstract or concrete. The “main sequence” explained in the derivation is the position where a package is neither ‘too abstract’ nor ‘too instable’. It also provides a link Object Mentor which provides a bash script that scans C++ directory structure and calculate all the metrics.

Links

Stable Abstractions Principle - gives a brief description of stable abstractions principle. The blog speaks about the relationship between stability and abstractness. It refers to Martin’s mathematical explanation of measurement of abstractness in a package.
Principles of Package Design - gives a brief hint of the stable abstraction principle. It also describes the relationship between stability and abstractness.
Principles of Object-Oriented Design - defines the principle and describes how to measure the abstractness of a package.

References

1. Stability
2. Design Principles and Design Patterns
3. Granularity
4. OO Design Principles & Metrics
5. Principles of Object-Oriented Design

External Links

1. A Summary of OO Principles
2. Principles of Agile Version Control: From OOD to TBD
3. Object Mentor - Published Articles
4. Principles of OOD by Robert Martin
5. What Makes A Good Object-Oriented Design?
6. Principles Of Object Oriented Design