Rust Best Practices

Overview

Reference guide for writing idiomatic, safe, and maintainable Rust code. Load topic-specific references based on your current task.

Quick Reference - What to Load

If you're...	Load
Creating types, seeing `String` or `i32` where domain types fit	`references/type-safety.md`
Handling errors, seeing `.unwrap()` or `.expect()`	`references/error-handling.md`
Using `bool` parameters, designing enums	`references/enum-design.md`
Designing public APIs, builders, trait implementations	`references/api-design.md`
Configuring Clippy, setting up lints	`references/clippy-config.md`
A lint fires and you're considering suppression	`references/clippy-config.md` — fix first, suppress only as last resort
Adding `#[allow]`/`#[expect]` annotations, dead code warnings	`references/clippy-config.md`
Structuring code, applying design patterns	`references/patterns.md`
Organizing modules, separating pure logic from I/O	`references/fcis.md`
Unsure how to use a crate, need documentation	`references/finding-docs.md`
Writing doc comments, examples in docs	`references/writing-docs.md`
Writing or running tests, choosing test strategy	`references/testing.md`
Using async/await, tokio, channels, spawn, timeout	`references/async.md`
Choosing mutex types, graceful shutdown, cancellation	`references/async.md`
Lifetime annotations, `'static`, HRTBs	`references/lifetimes.md`
Writing or reviewing unsafe code, FFI, MaybeUninit	`references/unsafe.md`
`Send`/`Sync` bounds, thread safety, Arc/Mutex	`references/send-sync.md`
Serde, JSON serialization, derive attributes	`references/serde.md`
`dead_code` on `Deserialize` structs, DTO dead fields	`references/dead-code-in-serde-structs.md`
Using aliri_braid, seeing `new()` conflicts or `Infallible` errors	`references/type-safety.md`

Error Message → Reference

If you see...	Load
"future cannot be sent between threads safely"	`references/send-sync.md` + `references/async.md`
"cannot be shared between threads safely"	`references/send-sync.md`
"borrowed value does not live long enough"	`references/lifetimes.md`
"does not live long enough"	`references/lifetimes.md`
"missing lifetime specifier"	`references/lifetimes.md`
"the trait `Send` is not implemented"	`references/send-sync.md`
"holding across an await point"	`references/async.md`
"`MutexGuard` held across await"	`references/async.md`
"higher-ranked lifetime error"	`references/lifetimes.md` (HRTBs)
"cannot infer type" with serde	`references/serde.md`
"duplicate definitions with name `new`" near a braid type	`references/type-safety.md` (aliri_braid gotchas)

Core Principles

Type Safety: Prefer newtypes over primitives. UserId(String) > String. Identifiers should be strings (or KSUIDs/UUIDs), not integers — you don't do math on IDs.

Error Handling: thiserror for libraries, color_eyre for applications. Reserve .expect() for initialization only. Never .unwrap() or .expect() in production runtime code.

Enums over Bools: enum Visibility { Public, Private } > is_public: bool.

Make Illegal States Unrepresentable: Use the type system to prevent invalid data.

Validate at Construction: Use TryFrom/newtypes with validation in constructors. A Port(u16) that rejects 0 is better than validating port values at every call site. Once constructed, the value is always valid.

Separate Pure Logic from I/O (FCIS): Organize modules so pure domain logic is separate from I/O and side effects. Pure domain modules contain types, validation, and business rules. service modules handle I/O, persistence, and external calls. See references/fcis.md.

Prefer Minimal Visibility: Start with the most restrictive visibility. Use pub(super) for parent-module access, pub(crate) for crate-internal access, and pub only when external crates need it. Apply the same discipline to struct fields.

STOP — Anti-Rationalization Table

Before writing code that matches these patterns, STOP and reconsider.

You're about to...	Common rationalization	What to do instead
Use `.unwrap()` outside tests	"It can't fail here" / "I'll fix it later"	Use `?`, `.expect("reason")`, or handle the error. Load `references/error-handling.md`.
Skip creating a newtype for a domain value	"It's just a String" / "Too much boilerplate"	Create the newtype. The boilerplate is the point — it prevents bugs. Load `references/type-safety.md`.
Skip input validation on a public constructor	"Callers will pass valid data"	Add `TryFrom` or a `fn new() -> Result<Self, E>`. Validate at construction, not at use.
Hold a `MutexGuard` across `.await`	"The lock is quick" / "It won't deadlock"	Restructure: clone the data, drop the guard, then await. Load `references/async.md`.
Write `unsafe` without a `// SAFETY:` comment	"It's obviously safe" / "I'll document later"	Write the SAFETY comment first. If you can't articulate the invariants, the code isn't safe. Load `references/unsafe.md`.
Use `bool` for a two-state concept	"An enum is overkill"	Create the enum. Bools are meaningless at call sites: `set_active(true)` vs `set_status(Status::Active)`. Load `references/enum-design.md`.
Add a catch-all `_ =>` to a match on your own enum	"I don't want to update every match"	That's exactly why you should — exhaustive matching catches forgotten variants at compile time.
Use `mem::transmute`	"I know the layout"	You probably don't. Use `from_ne_bytes`, `bytemuck`, or `zerocopy` instead. Load `references/unsafe.md`.
Suppress a lint instead of fixing the code	"It's just a style lint" / "The code is more readable this way"	Fix the code. Lints exist to improve quality. If clippy says `collapsible_if`, collapse it. If it says `manual_let_else`, use `let ... else`. Suppression is only for structural constraints you can't change (framework signatures, verified false positives). Load `references/clippy-config.md`.
Add `#[allow(dead_code)]`	"Conditionally dead — used in tests" / "Not used yet"	If only used in tests, the code IS dead — delete it. Refactor valuable tests to use live paths, or move test infrastructure behind `#[cfg(test)]`. Use `#[expect(dead_code, reason = "...")]` for interim work only, never `#[allow]`. Load `references/clippy-config.md`.
Leave `#[expect(dead_code)]` at end of task	"Field exists but not yet used" / "Will be wired up later"	Clean it up NOW. Either wire it up or remove it. `expect(dead_code)` is a WIP marker, not a permanent annotation.
Prefix a Serde field with `_` to suppress `dead_code`	"It's just a naming convention"	Never. `_field` changes the expected JSON/SQL key. Delete the field or use `#[expect(dead_code, reason = "...")]` with a structural reason. Load `references/dead-code-in-serde-structs.md`.
Keep unused fields on a `Deserialize` struct	"The field must match the schema" / "It documents the response"	Serde ignores unknown fields. Dead DTO fields aren't safety — they're coupling. Delete the field; comment the schema. Load `references/dead-code-in-serde-structs.md`.
Assume `Option<T>` handles missing JSON keys	"`Option` means optional" / "null and missing are the same"	They are not. `null` → `None` is serde_json. Missing key → `None` is an implicit derive feature. Always use `#[serde(default)]` on `Option<T>` fields where the key may be absent. Load `references/serde.md`.
Skip `skip_serializing_if` on `Option<T>`	"null in the output is fine"	It inflates payloads and breaks PATCH semantics. Pair `#[serde(default)]` with `#[serde(skip_serializing_if = "Option::is_none")]`. For three-state (missing/null/present), use `optional_field::Field<T>`. Load `references/serde.md`.

Authoritative Resources

Rust API Guidelines — Definitive guide from Rust library team
Clippy Lints — 750+ lints, searchable
Rust Design Patterns — Community patterns and anti-patterns
Effective Rust — 35 specific ways to improve your code

rust-best-practices