phanalist

E0023: The “Zone of Pain” Rule (Instability, Abstractness, Distance)

Imagine building a house.

• The Foundation must be very stable (hard to change) but very abstract (it’s just a flat slab, it doesn’t care what you build on it).
• The Wallpaper is very unstable (easy to change) and very concrete (it has a specific pattern and color).

If you build a house where the Foundation is made of wallpaper (unstable and concrete), the house falls down! This is called the Zone of Pain.

How the rule works

This rule calculates the “health” of a Namespace by looking at three ratios:

1. Instability (I): A ratio from 0 to 1. 0 means nothing depends on it. 1 means everyone depends on it.
2. Abstractness (A): A ratio from 0 to 1. 0 means it’s all concrete classes. 1 means it’s all interfaces and abstract classes.
3. Distance (D): The ideal namespace is either perfectly stable+abstract (a Foundation) or perfectly unstable+concrete (Wallpaper). The Distance metric tells us how far away your namespace is from this ideal balance.

---

❌ The “Zone of Pain” Example

A namespace full of concrete Database connection classes (A=0) that every other part of the application depends on (I=1).

Because everyone depends on it, it’s hard to change. But because it’s concrete, you want to change it often. This causes pain!

---

❌ The “Zone of Uselessness” Example

A namespace full of Interfaces (A=1) that nobody in the application actually uses or implements (I=0). It’s highly abstract, but totally useless.

---

✅ The Ideal Balance

1. Core Domain / Interfaces: Highly abstract (Interfaces), heavily depended upon (Stable).
2. Web Controllers: Highly concrete (Classes), nothing depends on them (Unstable).

---

Configuration

rules:
  E0023:
    max_instability: 0.8
    max_abstractness: 0.8
    max_distance: 0.5

The Junior’s Rule of Thumb:

If Phanalist flags your namespace for Distance (D), it means you have important files that are too specific, or abstract files that nobody uses. If a lot of code depends on a folder, that folder should contain mostly Interfaces!

This site is open source. Improve this page.