reading-like-proselisted

# Reading-Like-Prose ## Overview **Core principle:** Code is read far more often than it's written, and mostly by someone with no context — often you, months later. Structure it for that reader: top-down, one idea at a time, in the order a person would want to learn it. Good code reads like a well-edited paragraph, not a puzzle you assemble by jumping around. ## The Three Moves ### 1. One altitude per function A function should operate at a single level of abstraction. High-level intent and low-level mechanics in the same body forces the reader to change gears every line. - The top-level function reads like a **table of contents**: named steps, each a call. - Details live one level down, each in its own well-named function (see **naming-as-design**). - If a function mixes "what we're doing" with "how a byte gets shifted," extract the *how*. ### 2. Read top-down, important-first Order code the way a newspaper orders a story: headline first, details below. - The thing the reader most wants to know goes **first** — the main path, the answer. - Supporting detail comes **after**, so the reader never scrolls *up* to understand what they're reading. - Define-before-use is a compiler's need, not a human's. Where the language allows, order for the human. ### 3. Flatten the happy path Deep nesting hides the main story inside a staircase of conditions. - **Return early** on the exceptional cases — guard clauses at the top — so the happy path runs down the left margin, uninde