A guide to software complexity that anyone can understand

"Programs must be written for people to read, and only incidentally for machines to execute."

Abelson and Sussman (1985)

In this blog, we delve into software complexity. We first explain what software complexity is, show how you can find complex code in your Git repository, and then present some techniques to reduce software complexity.

What is software complexity?

The most accepted method to quantify software complexity is the Cyclomatic Complexity. The cyclomatic complexity is a measure the number of independent paths in a program. The number of paths in a program is calculated based on a control flow graph.

Let's take the following Python code:

COPYdef myfunc(a: int, b: int) -> int:
  c = 10
  if a > 100:
    if b < 50:
      c = 5
   else:
      c = 20
  else:
    c = 3
  return a + b * c

There is the corresponding control flow graph of the program. We annotated each node with its corresponding code. Each node in the graph is a circle, and an edge is an arrow going from one node to another.

The complexity is defined as

COPYComplexity = (Number of Edges)
             - (Number of Nodes)
             + 2 * (Number of Connected Components)

Other types of complexity

There are other contributors to software complexity, one being the size of your code and, more particularly, the length of a function.

One rule is that your code should always fit on your screen so you can read it and understand its control flow without scrolling.

How to find complex code

Text editors and IDE often have tools or plugins to evaluate the complexity of your code (example for Visual Studio or JetBrains). Such tools often depend on the language because they must parse the program and build its control flow.

Additionally, some tools highlight long functions and warn the developer when a function is becoming unreadable. Codiga finds complex and long functions in code and flags complex and long functions either on push or pull requests. Codiga annotates code in its interface and highlights complex (e.g. function having high cyclomatic complexity) and long functions, as shown below.

Codiga also lets you change complexity thresholds. By default, the Codiga code analysis engine flags any function with a cyclomatic complexity higher than 25 and any function longer than 40 lines. These thresholds can be changed in the project configuration.

Once you find complex code, it's now time to reduce it!

How to reduce software complexity

Let's remember the cyclomatic complexity formula. Based on a control graph, the cyclomatic complexity is defined as:

COPYComplexity = (Number of Edges)
             - (Number of Nodes)
             + 2 * (Number of Connected Components)

What increases complexity is not the number of nodes. It's the number of connected nodes in the control flow graph. The more you add nodes and connect them, the higher the complexity.

Looking at programming languages, there are the programming constructs that incur complexity:

• Nested branches: nested branches add new nodes in your control graph but also at least two connections for each new node
• goto, continue and break statement: goto statements add more connections between nodes in the control graph

Therefore, to reduce software complexity, you should:

• Write small functions: it reduces the number of nodes in your control graph. It reduces the size of the control graph and therefore, the number of edges. It also makes the code easier to understand.
• Avoid goto, continue and break statements: removing unnecessary connections between nodes of the control graph.

Wrapping Up

The state-of-the-art metric to evaluate software complexity is the Cyclomatic Complexity. This metric defines software complexity as the number of connections in your control graph.

There are multiple tools available to calculate software complexity. A simple tool is Codiga which flags functions with high cyclomatic complexity. Codiga also flags long functions. Codiga requires no setup and provides complexity metrics for more than 15 languages.

To reduce software complexity, developers must write small units of code (function, procedure, methods) but also avoid statements (goto, break, continue) that make the code harder to understand and increase its complexity.