Language / Language Spec Conventions

Language Spec Conventions

This document defines conventions used across docs/language/. It exists to keep the language specification consistent and easy to navigate for both:

  • first-time readers learning Silk, and
  • returning readers looking up precise rules.

See also: start for recommended reading paths.

Concept documents should be structured so readers can answer, quickly:

  • “What is this feature for?”
  • “What syntax does the compiler accept?”
  • “What are the rules and edge cases?”
  • “What works in the compiler?”

Recommended sections:

  1. One-paragraph summary
  2. Supported forms and constraints
  3. Surface syntax
  4. Semantics (evaluation order, scoping, control-flow behavior)
  5. Type checking rules (static requirements and diagnostics)
  6. Examples
  • minimal examples (smallest correct usage)
  • realistic examples (how the feature is used in real code)
  1. Common pitfalls
  2. Related documents
  3. Relevant tests (links to tests/silk/pass_*.slk and tests/silk/fail_*.slk)

Not every concept needs every section, but the goal is that a reader should never have to infer critical rules from examples.

Describe behavior directly#

State accepted syntax, semantics, target constraints, and diagnostics in the present tense. Explain a rejected form precisely rather than describing a development phase. Keep examples runnable, and label intentionally invalid code with its expected diagnostic.

Examples#

Examples in language docs should follow these rules:

  • Use 2-space indentation and spaces only.

  • Prefer complete, runnable snippets when possible:

    fn main () -> int {
      return 0;
    }
    
  • When an example requires multiple files, label them with comments, e.g.:

    // app/main.slk
    package app;
    
  • When an example is intentionally invalid (to show a rule), label it and mention the expected diagnostic.

Terminology#

These terms are used consistently across the spec:

  • Expression: a construct that produces a value and has a type.
  • Statement: a construct evaluated for its effects and sequencing.
  • Block: { stmt* }, a scope boundary and the unit of structured control flow. (Whether blocks are also expressions depends on the concept; docs must be explicit.)
  • Supported form: syntax accepted for the documented target and context.

Cross-References#

When describing a rule, link to the most relevant concept doc rather than restating it everywhere. Common cross-links include:

Source repository · Edit this page · View Markdown

Quick links

Type to search across the site. Use the up and down arrow keys to choose a result, Enter to open it, and Escape to close.