Reading diagrams / Topic 8 of 42

Shapes: doors and wide programs

The rule

A door is a package that every chain of arrows to some other package passes through. Packages in front of the door can reach what is behind it only through the door. Code behind it can change without them noticing, as long as the door stays the same.

To check a door, follow every chain of arrows from the first package. If any chain reaches the far package without passing the door, it is not a door.

rust-analyzer's maintainers describe hir as a door in their architecture notes: “The top-level hir crate is an API Boundary. If you think about ‘using rust-analyzer as a library’, hir crate is most likely the façade you'll be talking to.” The diagram lets you check the code against that sentence. In a review, a new arrow that goes around the door is the thing to look for.

A wide program has many packages on one level and many entry points. It is usually a set of separate features side by side, each built on shared parts below. Wide has no exact line, so statements about it give a number to check: count the packages on the widest level, and count the entry points, which can sit on any level.

A copy of rust-analyzer’s documented architecture.

Loading the layer diagram.

Icetakes again, the community reading site from the direct IO topic.

Loading the layer diagram.

Loading the worked examples and practice.