A few weeks ago I opened an Expression Set that I had written myself, and I could not say what it did.
The setting was TechnoStore — a fictional B2B retailer living in a real Developer Edition org of mine. The Expression Set decided which products a given account could see in the catalog, before anyone configured or priced anything. I had built it. I had tested it. And sitting in front of one branch of it, I could read every condition in the row and still not tell you, out loud, what the rule was for.
That is not a small embarrassment. It is the whole problem, and the subject of this post.
What declarative logic quietly changes
Moving qualification out of Apex and into an Expression Set is the right move, and I want to say so before I criticise anything. I have written about how account-aware qualification works and I stand by all of it. When commercial rules live in code, every change to a partner tier is a deployment. When they live in a decision table the platform consults at runtime, the same change is a new version authored with clicks.
But something else changes at the same moment, and it gets far less attention. Code arrives with a reader of last resort: a pull request, a reviewer, a commit message, a history recording who changed what and — if you are lucky — why. Declarative logic arrives with none of that. Nobody reviews an Expression Set. The change goes live because the person making it was permitted to make it.
So the safety net moves. In code, the net was review. In clicks, the net has to be readability — and readability is not automatic.
Taking logic out of code does not remove the need for review. It removes the place where review used to happen.
The one-sentence test
Here is the test I now apply. It is deliberately low-tech.
Take someone who did not write the rule. Show it to them. Ask them to say, out loud, in one sentence, what it does and why.
If they can, the rule is auditable. If they read the conditions back instead of explaining them, or manage the what and stall on the why, it is not — however correct it happens to be.
I did not invent this test. I inherited it from twenty years in schools. As a principal I saw the same pattern every year: any school rule that staff could not restate in one sentence got enforced differently by every teacher in the building. Not through carelessness — each of them had privately reconstructed a plausible reason, and the reasons did not match. Rules survive on being restatable. So does business logic.
Why the “why” is not optional
Most people accept that a rule should be understandable. What takes longer to land is that “what it does” is the easy half.
The conditions tell you the what. The why is the commercial decision underneath — the agreement, the policy, the risk somebody was avoiding — and it is the only part that can tell you whether the rule is still correct. A region gets added to a condition because of an agreement signed that quarter. Months later the agreement lapses. The rule still runs perfectly, qualifying every product exactly as written, and it is now wrong — quietly, with no error anywhere, because the reason it existed has gone and the rule has no memory of the reason.
A rule that carries its why can be retired. A rule that does not can only be feared.
An unexplainable rule is never deleted. It is inherited — and each new owner adds a condition rather than touching what they do not understand.
Three ways a rule stops being explainable
None of these are exotic; all three have happened in my own build.
It was never named for its purpose. A set named after its mechanics — “segment and region check” — describes the conditions. A set named after its decision — “reseller tier catalog limits” — describes the policy. The second name survives a year. The first needs archaeology.
It grew by amendment. Every change was small and justified at the time, and nobody re-read the rule as a whole afterwards. A handful of reasonable amendments add up to one rule nobody can restate.
Its reason lived in a meeting. What got recorded was the condition, not the conversation. Everyone who was not in the room inherits the what with the why stripped out.
Repairing a rule you cannot explain
When a rule fails the test, resist the urge to rewrite it straight away. Do this instead.
- Write the sentence you wish were true — “this rule limits resellers in this segment to the catalog their agreement covers” — before you touch a condition.
- Compare the sentence against the conditions. Anything the sentence does not account for is either a second rule hiding inside the first, or a leftover from something since fixed.
- Split rather than annotate. Two rules that each pass the test beat one heavily commented rule that does not.
- Put the sentence where the next person will find it — the description on the Expression Set, the notes on the version you activate — then run the test again with a colleague.
Step two is where the value hides. In my case, the branch I could not explain was two decisions welded together: a commercial limit, and a temporary workaround for a data problem long since solved. Neither was wrong alone. Together they were unreadable.
The audit you will actually be asked for
I care about this because of the question that eventually arrives: why did this account not see that product?
It comes from a rep who lost a deal, from a partner who believes they were treated differently, or — in a regulated setting — from somebody with a legal right to an answer. When it does, a person has to say a sentence out loud: “because resellers in that segment are limited to the catalog their agreement covers, and that product is not in it.”
“Because the Expression Set returned false” is not an answer. It is the complaint, restated in system language.
Two honest limits
Readability is not correctness. A rule can be beautifully explainable and completely wrong — the test is necessary, not sufficient. Take a known account, state from memory which products it should qualify for, and check the qualified list against that before activating a version.
Naming moves. Setup paths and feature naming in Revenue Cloud change from release to release, which is why I have described a practice rather than a click path.
Your next step
Open one Expression Set that you did not write. Read it. Then say out loud what it does and why — one sentence, without reading the conditions back.
If you can, you have found a well-built rule; go and see who wrote it, and how they named things. If you cannot, you have found the most useful object in your org today: a rule that is running, deciding, and accountable to nobody. Start with the sentence you wish were true.