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 fmtenforces 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 byuseimports, then items.//comment blocks above items document them: that’s what scribe turns into the API reference.
Naming
| Thing | Convention | Examples |
|---|---|---|
| Functions, variables | snake_case | vec_take, total, str_parse_int |
| Structs, enums, traits | PascalCase | Vec<T>, Point, Option<T> |
| Constants | SCREAMING_SNAKE | MAX_RETRIES, PAGE_SIZE |
| Modules | snake_case | module vec;, module task; |
| Free functions in a module | module-prefixed | vec_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
valis the default. Reach forvaronly when the variable is assigned again.valdoes not freeze aVec: methods that change it can still be called.constis for compile-time-known values; it never emits storage.
Types
- Spell out types in public signatures:
pub fnparameters and returns. Explicit types are the API contract scribe publishes. - Let inference work inside function bodies;
var i: i64 = 0where clarity needs it, barevalwhere it doesn’t. - Private-by-default fields: struct internals stay out of the public API; expose methods via
implblocks, exactly asVec<T>does.
Errors and effects
- Return
Result<T, E>/Option<T>for recoverable failure; propagate with?. PreferOption<T>to a home-made option enum. - Declare effects honestly in signatures; don’t paper over
IOorAllocto satisfy a capability boundary. Narrow the grant at theusesite instead.
Capabilities
- Import with the tightest grant that works, as in
use net with { Net }: a program’suselines 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 orextern "C"belongs behind a safe wrapperfn.
Control flow
while i < n { ... i = i + 1; }is the explicit loop; usefor x in ...when iterating a range or collection.matchon enums rather than chains ofif/tag checks: the compiler enforces exhaustiveness, so a new variant becomes a compile error at every unhandled site.deferfor cleanup next to acquisition, not at the bottom of the function.