|
We kind of know when code could be doing its job in a better way, when part of the design is no longer fit for purpose, when adding new features becomes harder than it should be. Part of this is logical complexity that requires refactoring and can only be detected and fixed by experienced programmers.
However code-base agility can also be damaged by structural complexity - the code is hard to understand, changes have unexpected side effects, the level of branching and merging increases, etc.
This kind of complexity can be measured because it is conceptually quite simple. For example, no method needs to contain control flow beyond some level of nesting - it can always be simplified by dividing it into more methods. Likewise classes and packages need not contain more than some level of complexity - they can always be divided into smaller classes and packages each with lower complexity.
This is what the XS metric is all about.
Monitoring overall XS lets project managers understand how much debt they are incurring when they emphasize schedules over refactoring - a productivity tax on future iterations.
XS measurements also help team leaders and programmers prioritize areas of the code for structural refactoring.
Measuring XS
Structure101 defines a framework to measure excess complexity in a code-base in such a way that we can relate the excess complexity of items at different levels of composition, and compare the total amount of excess complexity contained by different projects, subsystems, packages, etc.
This framework is reasonably simple, but now might be a good time to get a coffee.
First you should note that although Structure101 can work with different compositional hierarchies, the XS framework is based on the most "logical" of these - the package hierarchy. The XS framework is behind the measurement perspective, and it is best understood in the composition hierarchy with the package hierarchy selected. The Tracker web-application is also based on the XS framework.
The measurement of XS is best understood in the following steps:
- First measure the complexity of every item in the package hierarchy (i.e. every method, class, package, high-level package).
- Thresholds define when an item is considered excessively-complex.
- The degree of excessive complexity is calculated by normalizing the complexity values with respect to the thresholds. This gives an excessive complexity value for every item in the code-base.
- The degree of excessive complexity is related to the size of each item so that excessive complexity at lower (e.g. method) levels can meaningfully be related to items at higher (e.g. package) levels. This give a nominal excessively-complex lines of code for every item at every level.
- Finally, in order to compare the overall complexity of projects, subsystems, packages, etc., the total amount of excessively-complex lines of code contained by each item is summed up. This facilitates the drill-down on areas of relative over-complexity within a company or project.
Measuring Complexity
The first step to measuring excessive complexity is to measure the complexity at every level of design breakout. For Java, this means every method, class, package and high-level package is measured by the items and dependencies it immediately contains. (The XS measurement framework uses the package hierarchy for "containment").
For example, the complexity of a package is a function of the classes it contains, and the relationships between those classes.
Excess complexity is measured in terms of 2 metrics:
- Fat is a measure of the compositional (breakout) complexity at every level.
- Design Tangles are cyclic dependencies between packages, measured at the breakout of high-level packages ("design level").
The next step is to define when complexity becomes over-complexity.
Excessive Complexity
Having measured complexity metrics for each item in the code-base, we want to figure out which items are excessively complex and by how much. This is achieved by setting a threshold for the Fat for each item kind (method, class, package and design).
The industry norm for the maximum number of paths through a function is usually 10-15. By default, Structure101 takes the value of 15 as the threshold for Fat at method level. A value greater than 15 is therefore considered to be "excessive complexity".
Fat at the other points of breakout are measured as the number of edges in the corresponding dependency graph. There is no industry norm for this value, but we have found that 120 is a good start-point for most projects.
Structure101 lets you change these defaults at any or all scopes.
The threshold for design tangles is 0% - package-level dependency tangles are always considered undesirable.
Next we define to what degree an item is excessively complex.
Quantifying Excess Complexity
How do we differentiate between an item that is just over a complexity threshold and on that is, say, 10 times the threshold? The answer is normalization - we calculate a percentage from the value and the threshold as follows:
Max ( (Value - Threshold) / Value, 0 )
As an example, consider Fat for methods with a threshold of 15 (paths). Clearly a value less than or equal to the threshold will evaluate to 0% excess complexity, which is exactly as desired.
E.g. for value = 10: max( (10 - 15) / 10, 0 ) = max( -0.5, 0 ) = 0
Values greater than the threshold evaluate to numbers that converge to, but never reach 100%.
E.g. value = 30: (30-15) / 30 = 50%
E.g. value = 150: (150-15) / 150 = 90%
The following chart shows the approximate shape of the normalization curve.
Effect of Fat normalization formula
The value of design tangle metric is already a percentage (with a range 0-50%), and we do not normalize it further.
In the case where a high-level package both exceeds the Fat threshold and is tangled, we add the normalized Fat value to the Tangled value to get an overall excess complexity value for the item.
Now we need to relate the excessive complexity of items at different levels of composition.
Relating Items With Excessive Complexity
While every item, at every compositional level (method, class, package and high-level package), is measured for excess complexity, it is clear that a highly tangled breakout in a high-level package is going to be more disruptive to development processes than a single excessively complex method, and our measurement framework needs to reflect this to be truly useful.
This is achieved by relating the normalized degree of excess complexity to the size of the measured item. For example, if a package has excess complexity of 50% and a size of 1,000 lines of code (LOC), then we say that the item has an "XS" of 500 LOC. Nominally relating excess complexity to LOC lets us compare the excessive complexity of items at different levels in the code-base, and helps to prioritize complexity-related problems.
The final piece of the XS framework is to summarize the XS contained by every level of composition. This will enable the comparison of the amount of XS in projects, components, packages, etc.
Summarizing XS
We have defined an XS metric that can be used to compare the excessive complexity of items at different levels of the code-base. However, we also want to be able to home in on projects or subsystems that contain a relatively high number of items with XS at one or many levels. That is, we want to measure the total amount of XS contained by a composite item, rather than just the XS of that item's design breakout.
We do this by simply summing the XS of the item with the XS of all the items recursively contained by the item. So as well as counting the LOC contained by a package, class, etc., we also count the nominal number of excessively complex lines. This allows Structure101 to give a drill-down for size and XS at any level of composition.
| 
