37. Large-scale module conventions (pocket version)

TL;DR (5 lines)

Design advice must change code, not just prose.
Naming and conventions are technical levers.
Concrete before/after examples teach better than slogans.
Maintainability is visible in small code decisions.
The chapter should leave a reusable review rule behind.

Concrete Problem

Design and convention chapters often become prose-only advice with no proof that the rule changes code quality.

Coherent example

space demo/design

form BuildConfig {
  project_name: string
  retry_limit: int
}

proc validate_config(cfg: BuildConfig) -> int {
  if cfg.project_name == "" { give 11 }
  if cfg.retry_limit < 0 { give 12 }
  give 0
}

Global explanation

Design pages need code because design rules only matter when they improve a concrete contract. Naming, conventions, compatibility boundaries, and review habits are technical because they change how easily the code can be read and evolved.

Short exercise

Rename one vague field or procedure in the example and explain what ambiguity the new name removes.

Next best action

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