Code Comprehension

Code comprehension review

If overlay.md exists beside this file, read it before acting; it contains repository-specific bindings. This core remains usable without it.

A research-backed screen for how hard code is to understand (not how hard it is to test). Four decades of studies - including recent eye-tracking, EEG, and fMRI work - converge on a few high-confidence rules. Lead with those; treat the threshold numbers as screening heuristics, not hard limits, and let a consuming repo's own style guide or .editorconfig win on any conflict.

The high-confidence rules (apply these first)

1. Naming is the #1 factor. Across 40 years of studies, identifier quality

beats every structural metric. Misleading names are worse than meaningless ones. Fix misleading or cryptic names before touching anything else; prefer full words over abbreviations.

1. Cognitive load comes from working memory, not path count. Deep nesting,

long parameter lists, and dense data-flow (many live variables a reader must track) strain comprehension. McCabe's cyclomatic complexity is a weak proxy for human effort - use it for testing, not readability.

1. Indentation and layout matter a lot. Consistent indentation roughly

halves reading time versus unindented control flow; blank lines between logical chunks help.

1. Complexity perception saturates. Past a point (around cognitive complexity

15) more complexity barely changes perceived difficulty - so spend effort avoiding the extremes, not micro-optimizing already-simple code.

1. Small reviews work. Review effectiveness drops faster than linearly with

size; keep a change under roughly 200 lines so a reviewer can read it linearly.

Screening thresholds

Flag for review at "Review", refactor at "Refactor". Values between "Low" and "Review" are "moderate" — usually acceptable, but worth a quick "why" check. Numbers aggregate research and industry-tool convergence; adjust to the team and language.

| Factor | Low | Review | Refactor | Measure | | --- | --- | --- | --- | --- | | Nesting depth | 1-2 | 4-5 | >=6 | max nested control blocks | | Cognitive complexity (Sonar) | =16 | rule-based, penalizes nesting | | Method length | 100 | SLOC (no blanks/comments) | | Parameter count | =9 | params per method | | Boolean terms in an expression | =7 | operands / sub-expressions | | Line length | =121 | columns | | Data-flow (DepDegree) | few | many | dense, long-range | live def-use links | | Coupling (CBO) | =15 | classes a class depends on | | Cohesion (LCOM4) | 1 | 3-4 | >=5 | connected components in a class |

Cyclomatic complexity (McCabe) <=10 is the universal testing threshold - keep it, but don't use it to argue about readability.

Review priority order

1. Names - scan for misleading identifiers first, then cryptic abbreviations;

ensure consistent vocabulary.

1. Working-memory load - nesting depth, parameter count, and data-flow

(variable lifespans, cross-branch sharing). Extract methods, introduce well-named temporaries, or use a parameter object.

1. Size - over-long methods and over-large changesets; decompose.
2. Layout - consistent indentation, blank lines between chunks, line length.
3. Stop at the extremes - don't churn already-simple code to shave a metric.

Tailor to the audience: novices are hit hardest by nesting, recursion, and poor names; default a mixed team to the novice-friendly choice.

Evidence

The factor-by-factor research, the metric glossary, industry-tool thresholds, and the full citation list are in [references/research.md](references/research.md). The threshold numbers above are screening heuristics drawn from that evidence; the high-confidence rules at the top are the parts to rely on. A consuming repository binds its own style guide and any house thresholds in its overlay.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: JeremyKuhne
• Source: JeremyKuhne/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.