Manuel Pichler

Entries tagged as checkstyle

Tuesday, July 7. 2009

The value of complexity metrics - Cyclomatic Complexity (1/2)

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:

<?php
class CyclomaticComplexityNumber
{
public function exampe( $x, $y ) // (1)
{
if ( $x > 23 || $y < 42 ) // (1)
{
for ( $i = $x; $i >= $x && $i <= $y; ++$i ) // (1)
{
}
}
else
{
switch ( $x + $y )
{
case 1: // (1)
break;
case 2: // (1)
break;
default:
break;
}
}
}
file_exists('/tmp/log') or touch('/tmp/log');
}

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.

<?php
// ...
private function _countCalls(AbstractCallable $callable)
{
$callT = array(
TokenizerI::T_STRING,
TokenizerI::T_VARIABLE
);
$chainT = array(
TokenizerI::T_DOUBLE_COLON,
TokenizerI::T_OBJECT_OPERATOR,
);
$called = array();
$tokens = $callable->getTokens();
$count = count($tokens);
for ($i = 0; $i < $count; ++$i) {
// break on function body open
if ($tokens[$i]->type === TokenizerI::T_CURLY_BRACE_OPEN) {
break;
}
}
for (; $i < $count; ++$i) {
// Skip non parenthesis tokens
if ($tokens[$i]->type !== TokenizerI::T_PARENTHESIS_OPEN) {
continue;
}
// Skip first token
if (!isset($tokens[$i - 1]) || !in_array($tokens[$i - 1]->type, $callT)) {
continue;
}
// Count if no other token exists
if (!isset($tokens[$i - 2]) && !isset($called[$tokens[$i - 1]->image])) {
$called[$tokens[$i - 1]->image] = true;
++$this->_calls;
continue;
} else if (in_array($tokens[$i - 2]->type, $chainT)) {
$identifier = $tokens[$i - 2]->image . $tokens[$i - 1]->image;
for ($j = $i - 3; $j >= 0; --$j) {
if (!in_array($tokens[$j]->type, $callT)
&& !in_array($tokens[$j]->type, $chainT)
) {
break;
}
$identifier = $tokens[$j]->image . $identifier;
}
if (!isset($called[$identifier])) {
$called[$identifier] = true;
++$this->_calls;
}
} else if ($tokens[$i - 2]->type !== TokenizerI::T_NEW
&& !isset($called[$tokens[$i - 1]->image])
) {
$called[$tokens[$i - 1]->image] = true;
++$this->_calls;
}
}
}

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:

<?php
// ...
private function _countCalls(AbstractCallable $callable)
{
$called = array();
$tokens = $callable->getTokens();
$count = count($tokens);
for ($i = $this->_findOpenCurlyBrace($tokens); $i < $count; ++$i) {
if ($this->_isCallableOpenParenthesis($tokens, $i) === false) {
continue;
}
if ($this->_isMethodInvocation($tokens, $i) === true) {
$image = $this->_getInvocationChainImage($tokens, $i);
} else if ($this->_isFunctionInvocation($tokens, $i) === true) {
$image = $tokens[$i - 1]->image;
} else {
$image = null;
}
if ($image !== null) {
$called[$image] = $image;
}
}
$this->_calls += count($called);
}

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.

Posted by Manuel Pichler in php, php_depend, phpugdo, phpundercontrol, planet-php, projects at 21:20 | Comments (2) | Trackbacks (0)

Defined tags for this entry: checkstyle, cyclomatic complexity, design quality, npath complexity, php_depend, quality assurance, software metrics

Sunday, November 18. 2007

First release of phpUnderControl

This is the first release of the phpUnderControl tool. This tool aims to take the first steps with CruiseControl and PHP as easy as possible. phpUnderControl integrates three of the best PHP development tools into CruiseControl, combined with an easy setup routine and a small example project. With the provided XSL-Stylesheets the generated output of PHPUnit, PHP_CodeSniffer and phpDocumentor can be visualized in CruiseControl, as you can see in the following screenshot.

PHP coding violations visualized in CruiseControl

Getting started

Now let's take a look how to start with CruiseControl and phpUnderControl. The first things you need is a Java environment and a working installation of CruiseControl. I assume that Java is already installed and so I will not cover this topic here, but I suggest to use an original Java version from SUN instead of some versions bundled with linux distributions, because in combination with compiz or beryl the metrics view can be broken.

Getting a working CruiseControl installation is a simple task. Just download one of the provided zip archives, unpack the contents and start the application. Because this initial release of phpUnderControl is only tested with CruiseControl 2.7, I suggest to use this version for the moment. You can download this version, if you click the following link:

cruisecontrol-bin-2.7.zip

When the download has finished, just unzip the archive.

unzip cruisecontrol-bin-2.7.zip -d /opt/

For a detailed installation description how to install CruiseControl and how to configure it with PHPUnit I recommend an excellent article by Sebastian Nohn and the Continuous Integration chapter from the PHPUnit Pocket Guide written by Sebastian Bergmann.

Now, that you have a working CruiseControl, download the phpUnderControl tool from the following url and unpack the archive:

Small bugfix release, I left some system() calls in the source code.
phpUnderControl-0.1.1.tar.gz

phpUnderControl-0.1.0.tar.gz

Now, you need to change to the phpUnderControl/bin directory and execute the following command to install the required files. All files that the command line tool modifies, are backed up with the file extension .orig.

[mapi@frodo bin]$ ./phpuc.php install /opt/cruisecontrol-bin-2.7

Modifying CruiseControl files.
  File "main.jsp" modified.
  File "metrics.jsp" modified.
  File "xsl/buildresults.xsl" modified.

Installing new CruiseControl files.
  File "phpcs.jsp" installed.
  File "phpunit-pmd.jsp" installed.
  File "xsl/phpcs.xsl" installed.
  File "xsl/phpcs-details.xsl" installed.
  File "xsl/phpdoc.xsl" installed.
  File "xsl/phphelper.xsl" installed.
  File "xsl/phpunit-pmd.xsl" installed.
  File "xsl/phpunit-pmd-details.xsl" installed.

Modifying CruiseControl stylesheet.
  Creating backup of "css/cruisecontrol.css" as "css/cruisecontrol.css.orig".

All you need now is an application with that CruiseControl can work. phpUnderControl comes with a little example application which can be installed with the following command. This example doesn't require any version control system installation. Instead it uses a special tag, that CruiseControl provides.

[mapi@frodo bin]$ ./phpuc.php example -t ant /opt/cruisecontrol-bin-2.7
Creating required project directories.
  1. Creating CruiseControl project dir "projects/php-under-control".
  2. Creating Project input dir "php-under-control/source".
  3. Creating Project source dir "php-under-control/source/src".
  4. Creating Project test dir "php-under-control/source/tests".
  5. Creating Project build dir "php-under-control/build".
  6. Creating Project log dir "php-under-control/build/logs"
  7. Creating API documentation dir "/tmp/php-under-control/api"
  8. Creating Coverage dir "/tmp/php-under-control/coverage"

Creating example files.
  Creating file "php-under-control/source/src/Math.php".
  Creating file "php-under-control/source/tests/MathTest.php".

Creating project build file "php-under-control/build.xml".

Preparing CruiseControl "/opt/cruisecontrol-bin-2.7/config.xml.
  1. Loading "config.xml" data.
  2. Backup original "config.xml" as "config.xml.orig".
  3. Creating new project configuration.

Now change to the /opt/cruisecontrol-bin-2.7 directory and execute the cruisecontrol.sh or cruisecontrol.bat script to start CruiseControl. If you open your browser with this url http://127.0.0.1:8080/buildresults/php-under-control you will see something similar to the next screenshot.

CruiseControl Buildresult view after installation

PHPUnit features integrated

As mentioned in a previous post Sebastian Bergmann integrated support for Software Metrics and PMD in the PHPUnit 3.2 branch. Because he has used the original PMD format, the generated output was usable for CruiseControl without any modifications. Additionaly he integrated a third party contribution for Copy & Paste Detection that makes finding duplicate code fragments much easier. To show the results of this new report type the phpUnderControl tool provides modified versions of the original files pmd.xsl, pmd-details.xsl and metrics.jsp that can visualize the new records.

Copy & Paste Detection

PHP_CodeSniffer integration

The PEAR package PHP_CodeSniffer makes us PHP developers a present. With this handy tool coding guildline checks have become a really simple task. As a positive reaction on an other article Greg Sherwood, the lead developer of PHP_CodeSniffer, added support for the Checkstyle format to this package. Cool :-), with the upcoming 1.0.0RC3 release of PHP_CodeSniffer this package will work together with CruiseControl without any changes. The following screenshot shows the PHP_CodeSniffer result for the phpUnderControl example. Please note, all these errors are provoked and not the result of bad coding

PHP_CodeSniffer in CruiseControl

PLEASE NOTE: The current version 1.0.0RC2 has a small bug in the checkstyle output that causes CruiseControl to fail with the Checkstyle report. I hope this will be fixed in the RC3 release, but if you cannot wait just change line 720 in <pear-install>/PHP/CodeSniffer.php from

echo ' line="'.$line.' "column="'.$column.'"';

echo ' line="'.$line.'" column="'.$column.'"';

or you apply the following patch to <pear-install>/PHP/CodeSniffer.php

Index: CodeSniffer.php
===================================================================
RCS file: /repository/pear/PHP_CodeSniffer/CodeSniffer.php,v
retrieving revision 1.55
diff -r1.55 CodeSniffer.php
720c720
<                         echo ' line="'.$line.' "column="'.$column.'"';
---
>                         echo ' line="'.$line.'" column="'.$column.'"';

or you modify the build.xml file and use the XSL-Stylesheet from my previous post.

phpDocumentor integration

During the last user group meeting, while all others were hacking on some stuff. I thought this small javadoc legend in the "Coding violations" view must be fillable with the results of the standard PHP documentation tool phpDocumentor. The current integration is based on text matching onto the command line output of the phpdoc script which is not a perfect solution. For a future release of phpUnderControl there will be a custom implementation of the output converter that will process the documentation errors and warnings.

PHPDoc integration.

Finally

I hope this post and the phpUnderControl tool helps someone and was interesting for some of the readers. The current version is only tested under linux which means that I cannot say anything about windows, so I would be delighted if someone provides windows phpuc.bat or phpuc.cmd file.

Posted by Manuel Pichler in php, phpugdo, phpundercontrol, planet-php at 16:41 | Comments (5) | Trackback (1)

Defined tags for this entry: checkstyle, cruisecontrol, php, phpunit, php_codesniffer, pmd

Saturday, October 27. 2007

More QA with CruiseControl and PHP_CodeSniffer

I am using CruiseControl for some time now, to run all Unit Tests for a project continuous after each commit. Since Sebastian Bergmann started the development of PHPUnit 3.2 he added support for software metrics and PMD to PHPUnit, that give you further informations about the quality of your source code. These two features are really well integrated into CruiseControl, the only thing you need to do is to comment out the following lines in the main.jsp file.

<%--
<cruisecontrol:tab name="pmd" label="PMD">
<%@ include file="pmd.jsp" %>
</cruisecontrol:tab>
--%>

The next thing that is important for each project is the coding standard of a project, a company or at least a single person. Java has a nice tool called Checkstyle that checks all your code against a defined set of rules. I knew this tool really well from my diploma thesis, because I used Checkstyle to check the complete code against the Sun coding standards. Checkstyle is also really good integrated into CruiseControl, so that it checks on each build that your code meets the coding standards.

So what can a PHP developer do, to achieve the same support? This question is answered fast! There is a nice PEAR package that does nearly the same job as Checkstyle. The name of this package is PHP_CodeSniffer. This PEAR package provides a variety of pre defined coding standards like PEAR, ZEND etc., a small cli script phpcs to run PHP_CodeSniffer against your code and as best it provides an XML output generator. This output is not compatible with checkstyle but it is simple to transform into the Checkstyle format that is supported by CruiseControl. You can use the following stylesheet to transform the PHP_CodeSniffer output for your CruiseControl installation:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">

<xsl:output method="xml" version="1.0" encoding="UTF-8" omit-xml-declaration="no" indent="yes" />

<xsl:template match="/">
<checkstyle>
<xsl:apply-templates select="phpcs/*" />
</checkstyle>
</xsl:template>

<xsl:template match="file">
<file>
<xsl:attribute name="name">
<xsl:value-of select="@name" />
</xsl:attribute>
<xsl:for-each select="child::*">
<xsl:call-template name="entry" />
</xsl:for-each>
</file>
</xsl:template>

<xsl:template name="entry">
<error>
<xsl:attribute name="line">
<xsl:value-of select="@line" />
</xsl:attribute>
<xsl:attribute name="severity">
<xsl:value-of select="local-name()" />
</xsl:attribute>
<xsl:attribute name="message">
<xsl:value-of select="text()" />
</xsl:attribute>
</error>
</xsl:template>

</xsl:stylesheet>

You have to add the following lines to your ant build.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<project name="mapi-xplib-de" default="build" basedir=".">
...
<target name="checkstyle">
<exec executable="phpcs"
output="${basedir}/build/logs/codesniffer.pcs"
dir="${basedir}/source">
<arg line="--report=xml
--standard=MapiSource
--ignore=src/autoload src/" />
</exec>
<exec executable="xsltproc"
output="${basedir}/build/logs/checkstyle.xml"
dir="${basedir}/build/logs">
<arg line="${checkstyle.xslt} ${basedir}/build/logs/codesniffer.pcs" />
</exec>
</target>

<target name="build" depends="checkout,checkstyle,test" />
...
</project>

PLEASE NOTE I know that ant supports xsl transformation without external exec commands but it doesn't work with my current gcj installation.

Posted by Manuel Pichler in php, phpugdo at 19:03 | Comment (1) | Trackback (1)

Defined tags for this entry: checkstyle, continuous integration, cruisecontrol, php, php_codesniffer, quality assurance

(Page 1 of 1, totaling 3 entries)

Entries tagged as checkstyle

Entries tagged as checkstyle

Tuesday, July 7. 2009

The value of complexity metrics - Cyclomatic Complexity (1/2)

Sunday, November 18. 2007

First release of phpUnderControl

Getting started

PHPUnit features integrated

PHP_CodeSniffer integration

phpDocumentor integration

Finally

Saturday, October 27. 2007

More QA with CruiseControl and PHP_CodeSniffer

Projects

Further stuff

See also

Categories