14. Macros (pocket version)

TL;DR (5 lines)

Macros should pay their readability cost.
A bounded use case teaches better than a flashy demo.
Generated surface still needs a clear contract.
Debuggability matters as much as expressiveness.
Macro pages should teach restraint, not only power.

Concrete Problem

Macro chapters become misleading when they present expansion power without naming the readability cost.

Coherent example

space demo/macros

macro trace_value(name, value) {
  emit name
  emit value
}

Global explanation

Macros should be taught as controlled power tools. The question is not merely what they can generate, but whether they preserve or destroy the clarity of the resulting program surface.

Short exercise

Take one repetitive pattern from another chapter and argue whether it deserves a macro or a plain procedure.

Next best action

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