Vitte

39. Design of stable public APIs (pocket version)

TL;DR (5 lines)

  • Every chapter needs one concrete engineering story.
  • The contract matters more than the token list.
  • An invalid example should isolate the chapter's real lesson.
  • Global explanation beats line-by-line commentary.
  • The page should leave one reusable rule behind.

Concrete Problem

Generic chapters without a stable scenario produce repetition and weak retention.

Coherent example

space demo/generic

proc run(value: int) -> int {
  if value < 0 { give 11 }
  give value
}

Global explanation

The chapter should always return to the same core question: what contract does this construct give to the full block? That is the reason every page still needs one complete, testable example.

Short exercise

Take the coherent example and rewrite one line so that the chapter's central contract becomes even more explicit.

Next best action

Keep the example small, reproduce it locally, then continue to the full chapter if you need the broader context.