Files and layout
1. Let nomi fmt own the layout
Section titled “1. Let nomi fmt own the layout”Run nomi fmt -w after editing a .nomi file, or let the editor format on save through nomi-lsp. Don’t line code up by hand or fight a break fmt chose. What it does is in the tooling reference; the choices it leaves to you are these:
- A pipe inline or stacked (§7).
fmtkeeps the form you wrote. - A blank line between one-line statements to mark a step.
fmtkeeps one; it sets multi-line statements apart on its own. - A literal broken after its opening bracket stays one element per line even when it would fit. Delete that one line break to let
fmtjoin it. - A lambda body below its
->, closed byend, stays there. Writefn x -> x + 1to letfmtput a short body on the header’s line. - A blank line within a run of one-line declarations (
once,type,host fn) marks a group. Use one only at a real boundary.
2. Order declarations in a file
Section titled “2. Order declarations in a file”Order declarations by what helps the reader build the API model first.
The normal file shape is:
- imports, when needed
- file-level
oncevalues - public types, each followed by its
implblock, derives and interface impls - file-level functions: entry points first, then helpers
- standalone named tests
A type’s own operations and constants go in an impl Type block right after the type, and its derives and interface implementations follow that block. A once that describes a type (Float.pi, Status.ok, RetryPolicy.default) belongs in that block, so a caller reaches it through the type; a file-level once is for a value that belongs to the file, such as its configuration or a lookup table its functions share:
pub struct RetryPolicy attempts: Int delay: Duration end impl RetryPolicy pub once default = RetryPolicy{ attempts: 3, delay: Duration.seconds(1), } pub fn with_attempts(policy: RetryPolicy, attempts: Int) -> RetryPolicy {..policy, attempts:} end end derive Equatable for RetryPolicy impl Display for RetryPolicy fn to_string(policy: RetryPolicy) -> String "${policy.attempts} attempts" end end
An impl for a type from another file sits with the code that needs it.
This is a house style. Keep a different order when the local narrative is clearer, for example a tiny helper type right next to the one function that builds it, or a once right above the one function that reads it.
Attached tests (//!) stay with the declaration they exercise, even if that means a test appears before later functions. The ordering rule is for independent declarations.
3. Imports
Section titled “3. Imports”Import a file for its file-level functions and a type by name (spec §14 Import forms; tour: Modules & Imports). import std::io and then io.print(x) keeps the file’s name at each call, so the reader sees where print comes from. import std::calendar.Date and then Date.parse(text) names the type once, and every call through it says which type it works on. Don’t import a file only to write calendar.Date at every use.
import std::calendar.{Date, Months} std::io myapp::config.Config end
Several names from one path go in one selector list, as std::calendar above.
Use self only when you need both an owner (a file or an enum type) and selected children from it. self inside an owner selector binds the owner as well as the named items, so one line replaces two:
// no import shape.Shape shape.Shape.{Circle, Rectangle} end // yes import shape.Shape.{self, Circle, Rectangle}
If you need only the owner or only one member, don’t add self for its own sake: import shape.Shape and import shape.Shape.Circle stay as they are.
A dot-shorthand pattern (.Some(v)) names no imported variant, so don’t import a variant you only match with the dot form.
Use a file by its short name, the last part of its path: import db::posts, then posts.find(1). Where the short name is ambiguous (two files share it) or taken (a declaration has it), import the directory and write dir::file at the use; alias the file only where a directory import does not help (spec §14 Short names, Directory imports; tour: Modules & Imports). The path says which file at the use itself; an alias is one more name to look up.
// no import db::notifications as db_notifications jobs::notifications as job_notifications end // yes import db jobs end fn pending() -> Int db::notifications.pending() + jobs::notifications.pending() end
Import a directory to reach several files under it with one line: import views::admin, then admin::users.index(rows) and admin::reports::daily.show(). Don’t import a directory to reach one file whose short name is free; import views::admin::users and users.index(rows) say the same thing more briefly.