Skip to content

Document the "does this auto-show?" rule #23

@rmichaelthomas

Description

@rmichaelthomas

Severity: low (learnability)

Whether a statement prints is not learnable from the surface:

  • Auto-show: count, combine, standalone keep (and other value-producing expressions)
  • Silent: filter, sort, transform, weakens, assign
  • Conditional: expect (prints only on divergence), require (prints only on failure)

Each is individually defensible (value-producing vs in-place mutation vs metadata attachment), but as a set it's a memorization task. I repeatedly had to test "will this line print?" while building the vocabulary tour.

Recommendation

Add a one-line rule + a small table to docs/language/syntax.md, e.g.:

Expressions that produce a new value auto-show; verbs that mutate a value in place or attach metadata are silent; require/expect are silent on success and speak only on failure/divergence.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions