Cognitive complexity trend

What it means

A cognitive complexity trend tracks whether code is becoming easier or harder to understand under a defined analyzer and scope. It is more useful as a time series than as a single global score. Teams should separate newly added complexity from legacy inventory and explain major scope changes in the record.

Example

A service’s overall score rises after a rewrite, but the new code has lower complexity per changed line while old generated files were newly included. Segmenting the trend prevents a misleading conclusion about the rewrite.

Limitations

Trend movement can reflect parser upgrades, rule changes, file churn, or scope expansion rather than design change. A declining score may come from deleting difficult code, not improving the remaining code. Preserve measurement metadata.

How to use the signal

Weave can relate trend shifts to pull request size, review time, and rework rate. Use the analyzer’s own trend output and annotate releases so workflow context is not mistaken for causation.