Names and bindings
4. Naming
Section titled “4. Naming”The checker enforces case (spec §2 Naming Conventions); these rules cover what it leaves to you. Don’t add needless name suffixes: no _basic, _simple, _v2 or _new on a file, type or function unless a real counterpart exists to distinguish it from. A lone foo_basic with no foo_advanced is noise; call it foo.
Write an acronym as a word: Json, Toml, Uuid, HttpClient, IoError.
Split a file’s name into words as any other value name is split: std::code_points, order_lines.nomi, never orderlines. A name ends in _test only when the file holds tests, since _test.nomi is what marks a test file. A module that helps test another sits beside it as testing, as Go’s net/http/httptest does: std::sql::testing holds the fake Conn and the conformance suite, and code calls it testing.conformance(...). A file that imports two of them names each after its parent: import std::fs::testing as fs_testing.
Don’t repeat the file’s name in a type the file is about. A module with one error type calls it Error, and code outside writes it with the file’s name: uuid.Error, random.Error, locale.Error. Two modules’ errors then never collide, and uuid.Error says no less than UuidError. A module with several error types names each for what failed: Json.DecodeError, NumberParseError.
import std::uuid.Uuid fn read_id(text: String) -> Result<Uuid, uuid.Error> Uuid.parse(text) end
Nomi does not overload functions by argument type (spec §7 No Overloaded Functions). When two operations would want the same verb, put the distinction in the owner or the name. String.to_int(text) and Date.parse(text) are fine because the owners differ; within one owner, pick a name that describes the path, such as String.to_codepoints(text).
Name a function, binding or field that returns a Bool for what it asks. A state or an adjective takes is_ or has_: is_empty, is_valid, is_leap_year, has_children. A verb stays bare: Set.contains, String.starts_with, Iter.any_match, path.matches. A ? after an expression propagates a failure (§29), so it is no part of a name.
5. Leave a binding’s type off when inference settles it
Section titled “5. Leave a binding’s type off when inference settles it”That covers local bindings, once values (pub ones included) and lambda parameters, including an Iter.reduce seed (spec §5 Annotations and local inference; tour: Bindings & Expressions):
once upto = 400 once offsets = [(-1, 0), (1, 0), (0, -1), (0, 1)] total = Iter.reduce(1..=upto, 0, fn sum, n -> sum + n) lengths = Iter.reduce(words, {}, fn acc, word -> Map.put(acc, word, String.length(word)))
Write the type when nothing else pins the value down, such as an empty literal ([], Vector[], Set[], {}) or a None that no later use fixes: the checker rejects it with “type is not locally determined” until it has an annotation (once routes: Map<String, Handler> = {}, seen: Set<String> = []).
A struct field or a parameter with a default follows the same rule (spec §4 Field types from defaults, §7 Parameter types from defaults): misses = 0, home = Route`GET /admin/{$}` and mode = WriteMode.Replace need no type. Keep the type on a public field or parameter whose default is a call, such as limit: Int = default_limit(): a reader of the declaration then sees the type without looking up the function.
6. Thread one binding instead of inventing name ladders
Section titled “6. Thread one binding instead of inventing name ladders”Same-scope shadowing (spec §6 Shadowing and redeclaration; tour: Bindings & Expressions) lets you refine a value in place rather than inventing suffixed names:
// no: invented ladder fn normalize(name: String) -> String name_trimmed = String.trim(name) name_lower = String.lowercase(name_trimmed) name_lower end // yes: thread the binding fn normalize(name: String) -> String name = String.trim(name) name = String.lowercase(name) name end
Each step reads the value before it, so the compiler’s check for a binding that is never read still catches a step that throws one away.
When a value is intentionally ignored, use a discard name (spec §2 Discard names): _, or _name when a label makes the ignored value clearer. The same holds inside a pattern: write fn (_word, count) -> count, Some(_) -> True or [first, ..], and leave a struct pattern’s unneeded fields out (.Suspended{reason:}) rather than binding them.
A parameter the body ignores is written as its type alone when the type says all a reader needs: fn health(Request) -> Response, not fn health(_request: Request) -> Response (spec §7 Parameter Destructuring). Keep a discard name, _retries: Int, when the name says what the type does not.