Manuel Pichler

Software metrics are currently on everyone's lips and a frequently discussed topic. There are many conference talks, blog posts and other presentations that talk about software metrics. But to me it seems as if this subject is a closed book for many developers, so I decided to write this little post about a special category of software metrics, the complexity metrics.

Complexity metrics are a theoretical approach to measure the subjective complexity of a software fragment, where the words software fragment stand for a paraphrase for functions, methods, classes and nearly every logical unit that can be found in a software system. The most prevalent procedure to calculate complexity values is static code analysis, where an application parses the raw source code of a project, counts different statements and expressions and packs up the determined results in simple classification numbers. And with this information you already know the main concepts behind most software metrics, classification numbers and counting. As you can see there is no magic behind the scene, the only thing required is a good background knowledge to interpret those values.

The Cyclomatic Complexity Number or short CCN is the oldest complexity metrics. The first time this software metric was mentioned was 1976 by Thomas J. McCabe. This metric counts the available decision paths in a software fragment to determine its complexity. Each decision path starts with one of the conditional statements from the following list, so that it is fairly easy to detect them in existing source code.

• ?
• case
• elseif
• for
• foreach
• if
• while

A look at this list of statements may result in the questions: Is this list wrong, it doesn't list else and default? But it is correct. The assumption is that both statements will contain the defaut execution path of a program which also exists when there are no special cases to capture.

Each decision path gets the value 1 and the sum of all these values represents the Cyclomatic Complexity of the analyzed software fragment. Note that each function and method also counts with a value of 1 With this knowlegde we can now calculate the complexity of the following example code:

Based on the previous definition the Cyclomatic Complexity Number of the example code example is 5. But you may have noticed that this approach does not capture all decision paths that exist. We haven't catched those paths that came from the by the boolean expression || line 6 and && line 8, and the logical or expression in line 25. A variation of the Cyclomatic Complexity Number that also captures those paths is the so called CCN2. The CCN2 is the most widely used variation of this software metrics. Tools like PHPUnit, PMD and Checkstyle report it as Cyclomatic Complexity of an analyzed software fragment.

Now we get a complexity value of 8 when we apply the CCN2 to the previous example, what is a growt of the software's complexity of 60%.

Due to the fact that Cyclomatic Complexity Number was originally invented for procedural programming languages, this definition for the Cyclomatic Complexity Number still misses one element to measure the complexity of an object oriented software system. With the concept of exceptions a software gets additional decision paths for each catch statement used in the source code. While try contains the code for the regular execution code without special cases, similar to else and default statements.

• ?
• &&
• ||
• or
• and
• xor
• case
• catch
• elseif
• for
• foreach
• if
• while

Now that we know what the Cyclomatic Complexity Number is, what can we do with the measured information? We can find the complexity hotspots in a system, for example the top ten artifacts with the highest complexity, but this is only important during an initial analyses phase to get the big picture of an application. For a continuous inspection this information is not so important. A continuous analyses requires thresholds that help to categories calculated values. During the time four values have emerged as good thresholds for the Cyclomatic Complexity Number of a software system.

• A software fragment with a CCN value between 1-4 has low complexity.
• A complexity value between 5-7 is moderate and still easy to understand.
• Everything between 6-10 has a high complexity, while everything greater 10 is very complex and hard to understand.

You may ask, why should I care about the complexity of a software system, where is the value of benefit in this metric?

Mostly the complex parts of an application contain business critical logic. But this complexity has negative impacts on the readability and understandability of source code. Those parts will normally become a maintainence and bug fixing nightmare, because no one knows all the constraints, side effects and what's exactly going on in that part of the software. This situation results in the well known saying "Never touch a running system" which in turn mostly ends in copy&paste programming. The situation can even become more critical when the original author leaves the development team or the company.

Finally a small example how to apply the new knowledge about the Cyclomatic Complexity Number, thresholds and the negative impacts of complex software to an existing development process. The following source listing shows a complex method taken from PHP_Depend's source. This method has a Cyclomatic Complexity Number of 16 and I must admit that the original author needed some time to understand what was going on in this method.

The first thing to do is to make sure that the test suite is good enough to ensure that the required refactorings will not change the public behavior of the component or class. When this is donw and we are sure our that api breaks will be detected by the test suitewe can start to extract logic into separate methods.

The following example shows the result of the refactoring:

The subjective feeling of readability heavily depends on the complexity of control structures, as we can see by a comparison of the original and the refactored version of the method example. The new version with its Cyclomatic Complexity Number of 5 is much easier to read and understand.

This text is the first of two blog posts. The second article will give a short introduction into the NPath Complexity You liked this article and you are interested in this and other quality assurence related topics? - Then you should now order your copy of the Book Quality Assurance in PHP Projects. The book talks about nearly all aspect of quality assurence, with practical tips and expert knowledge contributed by certain PHP professionals.

This should be the final beta release for PHP_Depend 0.8.0. Beside some minor bugfixes, it contains a last API change for the log sub component. This change removes constraints to the ctor signature of a logger implementation, which is now part of a separate interface.

The following list shows all changes in this version. A detailed description of all issues can be found in the PHP_Depend issue tracker!

• #29 Tooltip for the Overview Pyramid.
• #34 Support for pattern based package filter.
• #37 Remove Logger - XML Config dependency.
• #38 The Logger interface should not force a default ctor-signature.

As always you can use PHP_Depend's pear channel or its svn repository, to check out this new version. And feel free to discuss and follow the PHP_Depend development on its dedicated mailing list.

Here a short follow up for the PHP_Depend release announcement, with hints on using PHP_Depend.

First I must explain that PHP_Depend is working package oriented. This means it heavily relies on @package and @subpackage annotations within the comment blocks. For these annotations PHP_Depend applies the following rules, these rules are borrowed from PEAR. Or was it PHPDocumentor?

1. function: The @package/@subpackage annotation in the file level comment is used for all functions declared within this file.
2. class/interface: The @package/@subpackage annotation within the class or interface comment is used for that type.
3. everything else: Everything that doesn't match on one of the previous rules is part of the +global Package.

With default settings PHP_Depend suppresses the +global Package, because it expects that this package contains classes from external libraries, like Zend Framework or eZComponents. If you use PHP_Depend for a project with less or no @package/@subpackage annotation, you should use the cli option --bad-documentation, which forces PHP_Depend to keep all classes, interfaces and functions within the +global package. This option was introduced with PHP_Depend - 0.8.0beta3.

The second important hint is related to exported charts and images. If your operation system, image viewer or browser supports SVG, you should use this format. The reason for this decision is really simple, SVG provides tooltips and so you get most informations from the generated graphics.

For the Overview-Pyramid this means, that you get a tooltip for the used acronyms.

PHP_Depend Overview-Pyramid with acronym tooltip

And within the JDepend-chart you get the package name as tooltip.

PHP_Depend JDepend-Chart with package tooltip

I hope this short introduction helps you while you are trying out PHP_Depend. If you are already using the metrics feature of PHPUnit, you should try out the new --phpunit-xml log option in the latest SVN-Revision.

To provide a flexible and extendable software, it is a good OO practice to reduce the dependencies between implementing classes. This could be achieved by developing against abstractions which means both, abstract classes and interfaces. By using abstractions instead of real implementation in the application you provide some sort of contract, that could be used by others to hook into the application with their own classes that fulfill the contract. Except the extensibility of an application a good abstraction reduces the risk of breaks in multiple subsystems when something was changed in a single package. But how to get rid of all these dependencies, doing this by hand will become an impossible job, at least for larger projects. At this point a tool should be used to assist the development process.

PHP_Depend is an adaption of the established Java development tool JDepend. This tool shows you the quality of your design in the terms of extensibility, reusability and maintainability. All these facts are influenced by the inter-package dependencies and the package abstraction that PHP_Depend visualizes in form of an abstract/instability chart and as a detailed XML report of all detected dependencies.

PHP_Depend calculates the following metrics by counting classes, interfaces and dependencies.

Ca - Afferent Couplings:

The number of other packages that depend upon classes within this package. This value is good indicator how changes to classes in this package would influence other parts of the software.

Ce - Efferent Couplings:

The number of other packages that classes from this package depend upon. This value indicates how sensitive this package is for changes to other packages.

I - Instability:

The ratio between efferent coupling (Ce) and the total package coupling (Ce + Ca) which is based on the following formula (Ce / (Ce + Ca)) and produces results in the range [0,1]. A value I=0 indicates a maximally stable package that depends upon nothing and I=1 indicates a total instable package that has no incoming dependencies but depends upon other packages.

A - Abstractness:

The ratio between abstract classes (ac) and the total of all classes (ac + cc) that is calculated by this formula (ac / (ac + cc)) that results in a value in the range [0,1]. A=0 means that all classes in this package are non-abstract while A=1 shows a package that only consists of abstract classes and interfaces.

With these values we can create a chart that visualizes the relationship between the instability (I) on the y-axis and the abstraction (A) on the x-axis.

Graphical view of PHP_Depend metrics

Because in a project not each package can achieve the optimal values of A = 1, I = 0 or A = 0, I = 1, we draw a diagonal between the two corners. This line is called the Main sequence and represents an average between abstraction (A) and instability (I). This means that packages near this line have a good mix between abstraction and instability. You can call these packages balanced. Because it is desirable for packages to be close to the Main sequence we have a fifth metric, the package distance (D) from this ideal.

D - Distance

The normalized distance has a value in the range [0,1] and is calculated by the formula ((A + I) - 1)

If you are interested in this subject and PHP_Depend you can check out the latest version, including the unit tests, from the subversion repository or simply install the PHP_Depend PEAR package. But be aware this software is at a very early stage.

mapi@arwen $ pear channel-discover pear.xplib.de
mapi@arwen $ pear install xplib/PHP_Depend-alpha

Now you can run PHP_Depend with the following command.

pdepend <source-dir> [<output-dir>]

If you are interested in the code coverage follow this link .

I will close this post with a cite of Robert Martin:

However, a metric is not a god; it is merely a measurement against an arbitrary standard.

The following sources were used for this post.

• OO Design Quality Metrics - An Analysis of Dependencies
• Managing Your Dependencies with JDepend
• JDepend