Skip to content

Docs/Language/Style Guide

Style Guide

Naming, formatting, and idiomatic patterns: the conventions the compiler and standard library follow.

~2 min read

On this page

The conventions the compiler (compiler/*.fd) and the standard library follow. fid fmt handles formatting; this page covers naming, structure and idiom.

Formatting

  • 4-space indent, no tabs. fid fmt enforces this.
  • Braces on the same line as the declaration or control flow.
  • One statement per line; no semicolon golf.
  • module name; is the first statement of every file, followed by use imports, then items.
  • // comment blocks above items document them: that’s what scribe turns into the API reference.

Naming

ThingConventionExamples
Functions, variablessnake_casevec_take, total, str_parse_int
Structs, enums, traitsPascalCaseVec<T>, Point, Option<T>
ConstantsSCREAMING_SNAKEMAX_RETRIES, PAGE_SIZE
Modulessnake_casemodule vec;, module task;
Free functions in a modulemodule-prefixedvec_take, task_run, json_parse

The module prefix is load-bearing: two modules can export the same local name, and callers disambiguate with module::name() or call the prefixed form. Prefer the prefix over a clever name.

Bindings

  • val is the default. Reach for var only when the variable is assigned again. val does not freeze a Vec: methods that change it can still be called.
  • const is for compile-time-known values; it never emits storage.

Types

  • Spell out types in public signatures: pub fn parameters and returns. Explicit types are the API contract scribe publishes.
  • Let inference work inside function bodies; var i: i64 = 0 where clarity needs it, bare val where it doesn’t.
  • Private-by-default fields: struct internals stay out of the public API; expose methods via impl blocks, exactly as Vec<T> does.

Errors and effects

  • Return Result<T, E> / Option<T> for recoverable failure; propagate with ?. Prefer Option<T> to a home-made option enum.
  • Declare effects honestly in signatures; don’t paper over IO or Alloc to satisfy a capability boundary. Narrow the grant at the use site instead.

Capabilities

  • Import with the tightest grant that works, as in use net with { Net }: a program’s use lines are its audit surface. (A { a, b } list after the module name is recorded but does not limit what is imported.)
  • Keep unsafe { } blocks small and named after the invariant they uphold; anything raw-pointer or extern "C" belongs behind a safe wrapper fn.

Control flow

  • while i < n { ... i = i + 1; } is the explicit loop; use for x in ... when iterating a range or collection.
  • match on enums rather than chains of if/tag checks: the compiler enforces exhaustiveness, so a new variant becomes a compile error at every unhandled site.
  • defer for cleanup next to acquisition, not at the bottom of the function.

Report an issue