When is a code-base too complex?

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.