Software Design X-Rays – Adam Tornhill & Sven Johann

Part 1
Part 2

Behavioral Code Analysis

It’s about the behavior of the organization and how this impacts the code. This is very similar to Conway’s Law.

Your Code is Crime Scene – Adam Tornhill


A hotspot is complicated code that we work with often. It’s a combination of Technical Qualifications like code and design smells and how often we change the code.

This idea was born out of the need to communicate with the stakeholders the important of tending to the code or eliminating code rot. Stakeholders can’t see what’s important and what’s not. All they see is the added business value. Someone can say they refactored something, but most of the time, there is no improvement of the value the program offers.

You don’t have to fix all the technical debt. Only the debt that changes frequently.

Key take-aways

  • Most code is in the long-tail. This is low-interest debt.
  • Hotspots only make up 2-4% of the total codebase, but attract 20-70% of all development activity!
  • Code quality issues in a hotspot are expensive. This is high interest debt.

The interest Rate

The interest rate, is the time I have to take to thing about adding a new feature or fixing a bug. In well written code, it doesn’t take long identify where the issue is and then fixing it. It usually can be fixed in one spot.

When code has a lot of rot, it takes longer to understand how the code works and where to fix or expand the code. The code also might be duplicated in multiple spot which also require fixing, making matters worse the duplicated code might not all be the same. This means you’ll have to implement a slightly different solution in many different place.

Trends analysis

To manage technical debt, the first step is not to take on more debt.

Trends tell you change for the better or for the worse. In comparison, hotspots are a snapshot in time. The don’t tell you if something is getting better or worse. They just tell you the current state.

By looking at trends, you can tell if what you’re doing is making the code better or worse.

Code Quality: Beyond a Single Metric

Measure Complexity via code health

  • Sample properties of the code that are known to correlate with maintenance costs and with higher risks of defects.
  • Aggregate the metrics and visualize
Examples of Code Health Issues
  • Low Cohesion, many responsibilities
  • Deeply Nested Logic, if-statements inside if statements
  • Brain Methods, large and complex functions that centralize the behavior of the module
  • Primitive Obsession, missing a domain language
  • Copy-Paste logic, missing abstractions
  • Learn more: []

There is an idea that code starts out great and then over time it degrades in to a mess. Adam Tornhill discovered this isn’t the case, most of the time the poor quality code was introduced in the first version.

Once a module degrades in code, the cost of refactor is very high with risks. So it becomes self-amplifying. Engineers don’t take on the work, instead they squeeze in a little more complexity to meet the requirements of their feature or fix their defect. This only make the code worse and harder to maintain.

So why wasn’t the code refactored? When you look at the commit history you find that a piece of code might have 50 contributors. The reason it hasn’t been refactored is because nobody knows the entirety of the code.

System Mastery

System Mastery is how much of the current code is written by the current team.

We tend to overestimate the complexity of unfamiliar code.

Code that has low cohesion has tons of responsibilities which is why so many engineer’s must touch the code.

Software Design X-Ray

A software X-Ray is a hotspot analysis at the function level.

Look for hotspot at a functional level, usually works great when some area’s of the application have thousands of lines, maybe even 10’s of thousands of lines have coupled code.

Software Design X-Ray’s Part 2

Change Coupling

Coupling is some type of dependency.

Change coupling is when changing one area of the code requires a change elsewhere in the code. You can assume the on the surface the other area of the code is unrelated. However, having to change the code as a result of a change means the code is coupled.

When you look at the research, you see that 5% to 20% of all code out there is duplicated to some extent.

Sometimes copying and pasting code isn’t bad. For example, coping and pasting code that is never touched again. Is this a bad thing? The challenge is putting determining when copying and pasting code is a bad thing and when it’s not. From an analytics perspective, it all looks the same.

If you using change coupling along with copy-paste detection, you get more insight into what copy-paste is bad and what copy-paste is good.

DRY (Don’t Repeat Yourself) is the enemy of decoupled. – Daniel Terhorst-North

There are cases where loose coupling is more important than duplicating code or logic. For example, in Mircoservices, loose coupling is way more important that duplicate code/logic.

What you want to avoid is duplicate behavior in two different Microservices that is often changed. It reveals a possible area to create a separate Microservices.

Change Coupling Gets More Expensive with Distance

Distance means architectural distance. Also means dependencies that cross-team boundaries.

Organization structure goes hand in hand with application architecture.

Team Topologies: Organizing Business and Technology Teams for Fast Flow – Matthew Skelton and Manuel Pais

Communication Architecture is the communication channels between individuals and teams. This goes hand in hand with Conway’s Law.

Team Structure Visualized in the Code

If a skill or is outside of your teams skillset, it needs to be brought in. For example, a database expert or security expert. This is work that your team can’t do and is something you have to create a boundary and could be an API you call.

When you have to work across teams, you have to have many meetings to keep insync. There are bottlenecks and delays. There are information sharing meetings, then there are status meetings. This is all in the service of being productive, but none of it gets the work, but about doing the work.

In the book, this is a way of covering up the symptoms, you want to keep meetings to a minimum. The only way to keep teams productive is to have them operate autonomously, meaning without having to engage another team every time they need a change. Basically, they need to be isolated in their work.

In Notes

Leave a comment

Your email address will not be published. Required fields are marked *