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.

forum: a discussion forum, with two recorded cuts. The buttons above the picture choose one.

Loading the abstraction cuts.

ledger: a ledger with spending limits, with two recorded cuts.

Loading the abstraction cuts.

Icetakes: the case code of the community reading site, with three recorded cuts.

Loading the abstraction cuts.

Loading the worked examples and practice.