Reading diagrams / Topic 38 of 42
Abstraction cuts: a chosen wall, and what crosses it
The rule
Good code hides most of its parts behind a few: an interface the rest of the program uses, and internal members only the inside should touch. The code rarely says where that wall is. So an agent proposes one, a cut: which definitions are inside, and which of them form the named interface.
Yichus checks the cut against the compiled program. Above the wall stand the definitions outside it that use something inside. An arrow from one of them to the named interface enters properly. An arrow that pierces the wall and ends at an internal member is a bypass: code outside that relies on a part the cut says is hidden. When the picture is wider than the page, it opens scrolled to a crossing; scroll it sideways to see the rest.
For each crossing, the compiler's dataflow also says what the inside value does there: it may reach the outside definition's result (return data), it only decides a branch (guard), or it is unused. A guard's value does not reach the result, but the branch it decides may still choose which result comes back. The line above the picture counts each kind, as in “2 bypasses may carry an internal value into an outside result”. The list under the picture, “Every incoming static use and its value flow”, gives each crossing.
The cut itself is the agent's. Its title, its description and which definitions it holds are agent-authored; the words after the dot in a title, such as proposed cut or declared subcomponent, are part of the agent's title. What crosses it is computed. Choose another cut and the answer changes: in forum, “Thread record · declared subcomponent” puts render_thread in the interface, so the same two uses are no longer bypasses.
Some programs hold source occurrences the compiler does not resolve: names whose target the snapshot does not record. Icetakes has 11, and its panels carry a note that begins “Unknown beyond resolved edges”. The arrows cover only the resolved uses, so a definition outside the wall that holds an unresolved occurrence may still reach past it. With no resolved bypass, the picture can't tell whether some use goes around the wall.
A bypass is a question for the author, not a verdict: either the wall is in the wrong place, or the code outside should go through the interface. Whether the cut is the right wall, the picture can't tell.
- An arrow through the wall to an internal member confirms a bypass; arrows only to the named interface rule one out, unless the definition holds an unresolved occurrence.
- Return data: the inside value may reach the outside result. Guard: its value does not, though its branch may choose the result. Unused: it does not affect the result.
- Whether the cut is the right wall, whether a run takes a return-data path, and what an unresolved occurrence names: the picture can't tell.
forum: a discussion forum, with two recorded cuts. The buttons above the picture choose one.
ledger: a ledger with spending limits, with two recorded cuts.
Icetakes: the case code of the community reading site, with three recorded cuts.
How to read this: what each mark in these pictures means
Loading the worked examples and practice.