How to assess coupling health in CodeScene

CodeScene has no single "coupling health" score, but four views together tell you whether coupling in a codebase is healthy and which way it is trending. This article walks through them in the order we recommend.

Why look at coupling

Once most of your files have good Code Health, delivery friction often comes from how the code is connected rather than how each file is written. Change coupling shows which parts of the code change together over time, whether or not they reference each other directly.

CodeScene treats two modules as coupled when they are modified in the same commit, by the same developer within a short period, or under the same ticket ID. Coupling is not bad in itself. It becomes a problem when it crosses boundaries you intended to keep separate, such as two components, two services or two teams.

Step 1: Define architectural components and enable trends

File-pair coupling is too detailed to judge a whole codebase. Architectural components group files into the building blocks you actually reason about, such as services, modules, layers or domains, so coupling can be read at system level.

Open your project configuration and go to the Architecture tab.
Open the Architectural Component Editor. It needs one completed analysis before it can show your files.
Navigate to the folder that holds your main structure and click Generate components. CodeScene creates one component per sub-folder. Add an optional prefix if you want a hierarchy.
Adjust where needed. You can map several folders to one component, for example application code plus its tests, using glob patterns such as myrepo/src/billing/**.
In the same configuration, enable architectural trends. They are off by default because they add analysis time, but they are what lets you follow coupling over time.
Click Submit. The components are used from the next analysis.

For large systems you can import component definitions from a CSV file (component name, glob pattern, no header row) and reuse them across projects.

Step 2: Read architectural change coupling and its trend

With components in place, the change coupling analysis shows which components change together and how strongly. This is the closest view to a system-level picture of coupling health.

The colour of each connecting line shows the trend of that dependency:

Line colour	Trend	What it usually means
Red	Growing stronger	The components are becoming more entangled. Investigate first.
Yellow	Stable	An established dependency. Check that it matches your intended design.
Blue	Weakening	The dependency is fading, often after a refactoring or split.

Compare what you see against your architectural principles. A healthy picture has few cross-component dependencies, most of them expected, and no red lines between components that should be independent. Several red lines between components that should not depend on each other are the clearest sign of unhealthy coupling.

If your system spans several repositories, the same view shows coupling between services, and you can drill down to the individual files involved, even across repositories and languages.

Step 3: Check coupling across team boundaries

The most expensive coupling is coupling that forces teams to coordinate. When two coupled components are owned by different teams, a single feature or bug fix needs work from both, and delivery slows.

Team overlay on change coupling: Groups the same coupling by the main contributing team of each component. Lines between teams show where work regularly crosses ownership.
Coordination needs: Shows which parts of the code need many contributors or several teams to coordinate. These are likely bottlenecks or areas without clear ownership.

Logical dependencies across team boundaries — This view is available under Code -> Change Coupling with "Teams" overlay selected

These views need teams configured in CodeScene. Coupling between components owned by one team is usually manageable. Coupling that crosses teams is where to focus, either by moving responsibilities or by splitting the code so teams can work in parallel.

Step 4: Find coupling magnets with Sum of Couplings

Sum of Couplings counts how often each file changes together with other files. The Sum of Couplings view lists files sorted by this number, so the top of the list shows the files most central to how the system changes.

A file near the top that is also a hotspot, or that has low Code Health, is a strong refactoring candidate. Changes there spread to many other files, so improving it reduces both risk and coordination.

When you find a surprising dependency, use X-Ray on the coupled files. It shows coupling at function level, so you can see exactly which parts of the code change together and why.

A simple coupling review routine

A short recurring review gives you a consistent read on coupling health. A monthly cadence, or a team retrospective, works well.

Count the red (strengthening) lines between architectural components, and note any that are new since the last review.
List the dependencies that cross team boundaries, and flag any that are growing.
Check the top 10 files in Sum of Couplings against your hotspots and their Code Health.
Pick one or two dependencies to break, and confirm in the next review that their lines have turned blue.

Record the counts each time. Tracked over a few months, they give you a practical healthy, problematic or unhealthy rating for each codebase.