38. Refactoring guided by types

Level: intermediate · Reading time: 9 min · Prerequisite: book/chapters/37-large-scale-module-conventions.html · Track: supplemental · Maturity: draft · Last review: 2026-05-09

Prerequisites: book/chapters/37-large-scale-module-conventions.html. See also: book/chapters/37-large-scale-module-conventions.html, book/chapters/27-grammar.html, book/chapters/31-build-errors.html.

Concrete Problem

Readers often learn type names but not what type contracts buy them in a real block.

Red Thread (Single Project)

A tiny reporting example uses integers, strings, and a form to make value contracts visible.

For what

This chapter helps the reader choose types based on meaning, not habit.

What you are going to do

You will inspect a typed example, identify where each type contract matters, then compare it to an invalid variant.

Coherent example

space demo/types

form Report {
  name: string
  retries: int
  ok: bool
}

proc score(r: Report) -> int {
  if not r.ok { give 0 }
  give r.retries + 1
}

Global explanation

The value of the chapter is not the list of types. It is the way each type removes ambiguity from the block: text is text, counters are numeric, flags are boolean, and the compiler can enforce that split.

Invalid case

proc bad_report() -> int {
  let name: int = "demo"
  give name
}

This invalid case is intentionally small. It exists to isolate the contract failure that the chapter is trying to teach.

Common pitfalls

• Using a type by habit instead of by domain meaning.
• Explaining individual fields without explaining the full contract.
• Forgetting that invalid examples should show a broken meaning, not just a weird token.

Short exercise

Take the example form and add one field whose meaning is obviously not numeric. Choose the type that makes the contract clearest.

Summary in 5 points

1. Types are contracts, not decorations.
2. A small form is a better teaching unit than isolated declarations.
3. The chapter should connect type names to domain meaning.
4. Invalid examples should show broken contracts clearly.
5. Type clarity reduces later diagnostic work.