What Is Code Complexity?

Complexity is the leading predictor of defect density. Functions with high cyclomatic complexity have statistically more bugs, take longer to understand, and are harder to test exhaustively. When complexity metrics are combined with centrality metrics, the result identifies the most dangerous files in a codebase — files that are both hard to understand and structurally critical.

Complexity also compounds over time. A function with complexity 15 is manageable. When a developer adds a feature, it becomes complexity 20. The next developer adds an edge case, making it 25. Each increment is small, but the cumulative effect is a function that requires a mental model too large for any individual to hold, increasing the probability of introducing bugs with each modification.

Tracking complexity metrics over time reveals whether a codebase is becoming more or less maintainable — a trend that correlates directly with long-term development velocity.

Cyclomatic complexity counts the number of linearly independent paths through a function's control flow graph. Every if, else, for, while, case, catch, and logical operator (&&, ||) adds one to the cyclomatic complexity. A function with no branching has complexity 1. A function with 10 if statements has complexity 11.

Cognitive complexity weights control flow elements by their nesting depth, recognizing that a nested if inside a loop inside a try-catch is harder to understand than three sequential if statements — even though both have the same cyclomatic complexity.

Halstead complexity measures the "volume" of a program based on the number of distinct operators and operands, providing a language-independent measure of code size and density.

These metrics are calculated at the function, class, and file level. Aggregations across the codebase reveal the distribution of complexity — whether it is evenly distributed or concentrated in specific hotspots.