Cognitive Code Analysis is an approach to understanding and improving code by focusing on how human cognition interacts with code. It emphasizes making code more readable, understandable, and maintainable by considering the cognitive processes of the developers who write and work with the code.
"Human short-term or working memory was estimated to be limited to 7 ± 2 variables in the 1950s. A more current estimate is 4 ± 1 constructs. Decision quality generally becomes degraded once this limit of four constructs is exceeded."
A c# version and a Java version are also available.
- Cognitive Complexity Analysis:
- Calculates a cognitive complexity score for each class and method
- Provides detailed cognitive complexity metrics
- Generate reports in various formats (JSON, CSV, HTML, Markdown, Checkstyle XML, JUnit XML, SARIF, GitLab Code Quality, GitHub Actions)
- Baseline comparison to track complexity changes over time
- Configurable thresholds and weights for complexity analysis
- Optional result cache for faster subsequent runs (must be enabled in config)
- Custom report generators
- Also provides Halstead Complexity Metrics (must be enabled in config)
- Also provides Cyclomatic Complexity Metrics (must be enabled in config)
- Cognitive Complexity Churn Analysis to identify hotspots in the codebase
- Generate reports in various formats (JSON, CSV, HTML)
- Custom report generators
composer require --dev phauthentic/cognitive-code-analysis
Create a project configuration file:
bin/phpcca init # interactive setup → creates phpcca.yaml in current directory bin/phpcca init --silent # non-interactive, all defaults bin/phpcca init --path=/path/to/phpcca.yaml
When phpcca.yaml exists in the current working directory, analyse and churn load it automatically. Use --config to specify a different file.
Cognitive Complexity Analysis
bin/phpcca analyse <path-to-folder> bin/phpcca analyse <path-to-folder> --config=custom.yaml # explicit config overrides auto-discovery
Generate a report, supported types are json, csv, html, markdown, checkstyle, junit, sarif, gitlab-codequality, github-actions.
bin/phpcca analyse <path-to-folder> --report-type json --report-file cognitive.json
You can also pass a baseline file to compare the results to. The JSON report is used as baseline. The output will now show a delta if a value was changed.
bin/phpcca analyse <path-to-folder> --baseline cognitive.json
Churn is a measure of how much code has changed over time. It helps to find the most changed and complex areas in your codebase, which are often the most error-prone and difficult to maintain. Read the Churn - Finding Hotspots documentation for more details.
Note that this requires a version control system (VCS) to be set up, such as Git.
bin/phpcca churn <path-to-folder>
The Cognitive Code Analysis VS Code extension shows methods above your configured threshold as diagnostics while you type.
It uses the phpcca installed in your project's vendor/bin and respects your phpcca.yaml.
- Cognitive Complexity Analysis
These pages and papers provide more information on cognitive limitations and readability and the impact on the business.
- Cognitive Complexity
- Cognitive Complexity Wikipedia
- Cognitive Complexity and Its Effect on the Code by Emanuel Trandafir.
- Human Cognitive Limitations. Broad, Consistent, Clinical Application of Physiological Principles Will Require Decision Support by Alan H. Morris.
- The Magical Number 4 in Short-Term Memory: A Reconsideration of Mental Storage Capacity by Nelson Cowan
- Neural substrates of cognitive capacity limitations by Timothy J. Buschman,a,1 Markus Siegel,a,b Jefferson E. Roy, and Earl K. Millera.
- Code Readability Testing, an Empirical Study by Todd Sedano.
- An Empirical Validation of Cognitive Complexity as a Measure of Source Code Understandability by Marvin Muñoz Barón, Marvin Wyrich, and Stefan Wagner.
- Halstead Complexity
- Cyclomatic Complexity
- Sonars Understandability / Cognitive Complexity
The tool computes complementary complexity metrics at class and method level. Optional metrics are enabled in phpcca.yaml.
| Category | Metric | Description |
|---|---|---|
| Cognitive Complexity | Score | Weighted sum of structural inputs (lines, arguments, variables, branching, etc.); each input contributes logarithmically above a configurable threshold |
| Understandability | Score | Sonar-style control-flow complexity, separate from the weighted cognitive score; risk bands: 0–5 low, 6–10 medium, 11–15 high, 16+ very high |
| Cyclomatic Complexity | Score | Number of linearly independent paths: base 1 plus decision points and logical operators; risk bands: 1–5 low, 6–10 medium, 11–15 high, 16+ very high |
| Halstead | Volume | Implementation size derived from operators and operands (N × log₂(n)) |
| Halstead | Difficulty | Effort required to understand the code ((n₁ / 2) × (N₂ / n₂)) |
| Halstead | Effort | Mental effort to develop or maintain the code (D × V) |
Class: \WP_Debug_Data ┌───────────────────┬──────────────┬───────────┬─────────┬─────────────┬────────────┬────────────┬────────────┬────────────┬────────────┐ │ Method Name │ Lines │ Arguments │ Returns │ Variables │ Property │ If │ If Nesting │ Else │ Cognitive │ │ │ │ │ │ │ Accesses │ │ Level │ │ Complexity │ ├───────────────────┼──────────────┼───────────┼─────────┼─────────────┼────────────┼────────────┼────────────┼────────────┼────────────┤ │ check_for_updates │ 6 (0) │ 0 (0) │ 0 (0) │ 0 (0) │ 0 (0) │ 0 (0) │ 0 (0) │ 0 (0) │ 0 │ │ debug_data │ 1230 (6.373) │ 0 (0) │ 1 (0) │ 105 (3.073) │ 20 (0.788) │ 58 (4.025) │ 3 (1.099) │ 33 (3.497) │ 18.855 │ │ get_wp_constants │ 144 (3.761) │ 0 (0) │ 1 (0) │ 9 (0.875) │ 0 (0) │ 5 (1.099) │ 1 (0) │ 5 (1.609) │ 7.345 │ │ get_wp_filesystem │ 60 (0) │ 0 (0) │ 1 (0) │ 9 (0.875) │ 0 (0) │ 1 (0) │ 1 (0) │ 0 (0) │ 0.875 │ │ get_mysql_var │ 15 (0) │ 1 (0) │ 2 (0) │ 2 (0) │ 0 (0) │ 1 (0) │ 1 (0) │ 0 (0) │ 0 │ │ format │ 60 (0) │ 2 (0) │ 1 (0) │ 11 (1.03) │ 0 (0) │ 5 (1.099) │ 1 (0) │ 5 (1.609) │ 3.738 │ │ get_database_size │ 14 (0) │ 0 (0) │ 1 (0) │ 4 (0.336) │ 1 (0) │ 1 (0) │ 1 (0) │ 0 (0) │ 0.336 │ │ get_sizes │ 125 (3.512) │ 0 (0) │ 1 (0) │ 14 (1.224) │ 0 (0) │ 9 (1.946) │ 2 (0.693) │ 5 (1.609) │ 8.984 │ └───────────────────┴──────────────┴───────────┴─────────┴─────────────┴────────────┴────────────┴────────────┴────────────┴────────────┘
Class: Doctrine\ORM\Tools\Pagination\Paginator ┌───────────────────────────────────────────┬────────┬───────────┬─────────┬───────────┬──────────┬───────┬────────────┬───────────┬────────────┐ │ Method Name │ Lines │ Arguments │ Returns │ Variables │ Property │ If │ If Nesting │ Else │ Cognitive │ │ │ │ │ │ │ Accesses │ │ Level │ │ Complexity │ ├───────────────────────────────────────────┼────────┼───────────┼─────────┼───────────┼──────────┼───────┼────────────┼───────────┼────────────┤ │ __construct │ 10 (0) │ 2 (0) │ 0 (0) │ 1 (0) │ 1 (0) │ 1 (0) │ 1 (0) │ 0 (0) │ 0 │ │ getQuery │ 4 (0) │ 0 (0) │ 1 (0) │ 1 (0) │ 1 (0) │ 0 (0) │ 0 (0) │ 0 (0) │ 0 │ │ getFetchJoinCollection │ 4 (0) │ 0 (0) │ 1 (0) │ 1 (0) │ 1 (0) │ 0 (0) │ 0 (0) │ 0 (0) │ 0 │ │ getUseOutputWalkers │ 4 (0) │ 0 (0) │ 1 (0) │ 1 (0) │ 1 (0) │ 0 (0) │ 0 (0) │ 0 (0) │ 0 │ │ setUseOutputWalkers │ 6 (0) │ 1 (0) │ 1 (0) │ 1 (0) │ 1 (0) │ 0 (0) │ 0 (0) │ 0 (0) │ 0 │ │ count │ 12 (0) │ 0 (0) │ 1 (0) │ 1 (0) │ 1 (0) │ 1 (0) │ 1 (0) │ 0 (0) │ 0 │ │ getIterator │ 46 (0) │ 0 (0) │ 2 (0) │ 9 (0.875) │ 2 (0) │ 3 (0) │ 2 (0.693) │ 2 (0.693) │ 2.262 │ │ cloneQuery │ 13 (0) │ 1 (0) │ 1 (0) │ 3 (0.182) │ 0 (0) │ 0 (0) │ 0 (0) │ 0 (0) │ 0.182 │ │ useOutputWalker │ 8 (0) │ 1 (0) │ 2 (0) │ 1 (0) │ 1 (0) │ 1 (0) │ 1 (0) │ 0 (0) │ 0 │ │ appendTreeWalker │ 11 (0) │ 2 (0) │ 0 (0) │ 1 (0) │ 0 (0) │ 1 (0) │ 1 (0) │ 0 (0) │ 0 │ │ getCountQuery │ 25 (0) │ 0 (0) │ 1 (0) │ 4 (0.336) │ 1 (0) │ 2 (0) │ 1 (0) │ 1 (0) │ 0.336 │ │ unbindUnusedQueryParams │ 17 (0) │ 1 (0) │ 0 (0) │ 6 (0.588) │ 0 (0) │ 1 (0) │ 1 (0) │ 0 (0) │ 0.588 │ │ convertWhereInIdentifiersToDatabaseValues │ 11 (0) │ 1 (0) │ 1 (0) │ 5 (0.47) │ 1 (0) │ 0 (0) │ 0 (0) │ 0 (0) │ 0.47 │ └───────────────────────────────────────────┴────────┴───────────┴─────────┴───────────┴──────────┴───────┴────────────┴───────────┴────────────┘
If you find a bug or have a feature request, please open an issue on the GitHub repository.
Especially the AST-parser used under the hood to analyse the code might have issues with certain code constructs, so please provide a minimal example that reproduces the issue.
Copyright Florian Krämer
Licensed under the GPL3 license.