Measuring complexity

Structure101 lets you define complexity limits at any level of decomposition (design, package, class and method). It can then take you directly to specific violations, as well as giving you an overview of how violations are distributed across the code-base.

Find and analyze design tangles. A navigable list takes you directly to design tangles, and graphs indicate the "minimum feedback set".

Measure excessive structural complexity. A simple framework measures the degree to which structure at any level exceeds complexity thresholds.

Summary reports. A report gives a quick indication of the size and complexity of your code-base, and the areas of highest over-complexity.

Removing and avoiding excessive structural complexity will make your code-base easier to develop, modify, extend, test, reuse, deploy, etc.

Understanding tangled code

If you don't keep an eye on your package-level structure, cyclic dependencies will most likely creep in. Cyclic dependencies prevent you from releasing, developing or testing packages independently (Robert Martin's Acyclic Dependencies Principle (ADP)). Structure101 exposes package-level cycles ("Tangles") and helps you figure out which set of dependencies you could remove in order to break the cycles. The Dependency Breakout then lets you discover what code would need to be changed.

Figure: Auto-partitioning indicates any set of nodes that are cyclically dependant as a cluster with a red border. Full screenshot

Figure: The minimum set of dependencies that would need to be removed in order to render the graph acyclic are drawn in red. Full screenshot

Figure: A list of tangled package diagrams is sorted by depth (higher tangles are generally considered to be worse) and can be used to navigate to the tangles.
Full screenshot

Measuring XS

Structure101 defines a software complexity metric called XS.  The principal of XS is very simple, but if you keep your XS close to zero, your structure will be considerably simpler (easier to develop, modify, extend, test, reuse, deploy, etc.) than the vast majority of code-bases in the world. 

A unique characteristic of the XS metric is that it can be applied to every item at every level of the hierarchy.  An XS value of 0 is good - it means that the code is not excessively complex (has not exceeded the set limit).

XS considers only two structural measures - "Fat" and "Tangle". 

Fat is the degree to which an item exceeds a size threshold and is applied at every level of the hierarchy.  Fat is measured as Cyclomatic Complexity at the method level, and the analogous measure of the number of edges in the dependency graph is used at all other levels.

Tangle is the degree to which package dependencies are cyclic and is applied only at the design level (i.e. to the contents of high-level packages).  Tangle is measured as the number of "wrong", or upward, dependencies as a percentage of all dependencies on a dependency graph. The Tangle metric is only measured at the package level where it does the most damage (see Bob Martin's Acyclic Dependency Principle (ADP))

Any excessive Fat and Tangle is multiplied by the amount of code in the item to give the XS value for that item.  In this way, problems higher in the hierarchy are "awarded" a higher XS value.  This is important because higher-level problems (such as architectural tangles) tend to cause more chaos that lower-level problems (however widespread low-level problems, such as high method CC, can add up to as big a problem as a tangle at the top level).  Relating XS to the amount of code also allows us to indicate the average amount of the code that is excessively complex at any level, and so a way to understand the relative complexity of different projects or parts of projects.

Figure: The Measurement perspective relates the amount of XS (red) to the amount of code in an item so that you can compare the size and complexity of the different areas of your code-base. Full screenshot

Figure: A list of items that violate Fat and/or Tangle thresholds helps you prioritize problems and tackle them according to the impact they are having on your team productivity. Full screenshot

Figure: A pie chart shows you the relative contribution of problems to the overall XS value.  Selecting a slice of the pie filters the list to show just items with the selected problem. Full screenshot

Figure: The XS configuration can be modified to include/exclude specific scopes and to change the threshold values. Full screenshot

Structure101 summary reports

Structure101 provides a rich set of features to help you understand and analyze the structure of your code-base.  Sometimes you will just want a quick overview of the current state - especially if you're just starting to look at your structure.  The structure101 client provides a summary report with some vital statistics that you can quickly review yourself, or which can be saved and sent to others (in HTML).  The report can also be automatically generated in batch mode without starting the client application.

You can optionally view the report with notes and tips (example), or without notes and tips (example).  Excessive structural complexity is avoidable - here is a project without XS (almost!).

The structure101 web application provides much more detailed reports, including trending structural data over time and cross project comparisons.

Table: A table gives several measures of the total size of the code-base.

Table: The excessive structural complexity indicates how much avoidable complexity has been accumulated. In this case, 65% of the code is excessively complex (high).

Table: This table informs you how tangled your code is at 3 levels.

Table: The summary report tells you what problems at what levels are causing XS.

Table: For each metric and level, the top few offenders are listed.

Table: You can optionally switch on notes that both explain the report in more detail, and suggest how to use Structure101 to get more information.