Rust Guidelines

Overview

Comprehensive Rust guidelines combining Microsoft’s Pragmatic Rust Guidelines (48 production rules) with community patterns for ownership, type-driven design, domain modeling, and ecosystem integration. For specialized topics see: rust-unsafe, rust-async, rust-performance, and domain skills (rust-web, rust-cli, etc.).

Full Microsoft reference: @microsoft-rust-guidelines.md

Error Handling

// BAD: library panics on bad input
pub fn parse(input: &str) -> Data {
    if input.is_empty() { panic!("empty"); }
    // ...
}

// GOOD: return Result
pub fn parse(input: &str) -> Result<Data, ParseError> {
    if input.is_empty() { return Err(ParseError::EmptyInput); }
    // ...
}

Domain Error Strategy

#[derive(thiserror::Error, Debug)]
pub enum AppError {
    #[error("Invalid input: {0}")]
    Validation(String),

    #[error("Service temporarily unavailable")]
    ServiceUnavailable(#[source] reqwest::Error),

    #[error("Internal error")]
    Internal(#[source] anyhow::Error),
}

impl AppError {
    pub fn is_retryable(&self) -> bool {
        matches!(self, Self::ServiceUnavailable(_))
    }
}

API Design

Type-Driven Design

// Newtype: validate once, trust forever
struct Email(String);
impl Email {
    pub fn new(s: &str) -> Result<Self, ValidationError> {
        validate_email(s)?;
        Ok(Self(s.to_string()))
    }
}

// Type State: compiler enforces valid transitions
struct Connection<State>(TcpStream, PhantomData<State>);
struct Disconnected;
struct Connected;
struct Authenticated;

impl Connection<Disconnected> {
    fn connect(self) -> Connection<Connected> { ... }
}
impl Connection<Connected> {
    fn authenticate(self) -> Connection<Authenticated> { ... }
}

// BAD: stringly typed — wrong order compiles fine
fn connect(host: &str, port: &str, timeout: &str) { ... }
connect("8080", "localhost", "30"); // swapped!

// GOOD: strong types prevent misuse at compile time
struct Host(String);
struct Port(u16);
struct Timeout(Duration);
fn connect(host: Host, port: Port, timeout: Timeout) { ... }

// BAD: boolean parameters — unclear at call site
fn fetch(url: &str, use_cache: bool, validate_ssl: bool) { ... }

// GOOD: options struct
struct FetchOptions { use_cache: bool, validate_ssl: bool }
fn fetch(url: &str, options: FetchOptions) { ... }

// BAD: Option<Option<T>> — ambiguous semantics
fn find(id: u32) -> Option<Option<User>> { ... }

// GOOD: explicit enum
enum FindResult { Found(User), NotFound, Error(String) }

Ownership & Lifetimes

Common Ownership Errors

Key Anti-Patterns

// BAD: clone to dodge borrow checker
for item in data.clone() { println!("{}", item); }
use_data(data);

// GOOD: borrow when you don't need ownership
for item in &data { println!("{}", item); }
use_data(data);

// BAD: holding reference prevents mutation
let mut data = vec![1, 2, 3];
let first = &data[0];
data.push(4); // ERROR: data is borrowed

// GOOD: copy the value out
let first = data[0]; // i32 is Copy
data.push(4); // OK

// BAD: loop consumes the vector
for s in strings { println!("{}", s); }
println!("{:?}", strings); // ERROR: moved

// GOOD: iterate by reference
for s in &strings { println!("{}", s); }
println!("{:?}", strings); // OK

Lifetime Elision Rules

The compiler infers lifetimes in this order:

1. Each reference parameter gets its own lifetime
2. If exactly one input lifetime, it applies to all outputs
3. If &self/&mut self exists, its lifetime applies to all outputs

When elision doesn’t work, annotate explicitly. Use meaningful names:

struct Parser<'src> {
    source: &'src str, // 'src not 'a — more readable
}

Smart Pointers & Resource Management

Smart Pointer Decision

Decision Flowchart

Need heap allocation?
├─ Yes → Single owner?
│        ├─ Yes → Box<T>
│        └─ No → Multi-thread?
│                ├─ Yes → Arc<T>
│                └─ No → Rc<T>
└─ No → Stack allocation (default)

Have reference cycles?
├─ Yes → Use Weak for one direction
└─ No → Regular Rc/Arc

Need interior mutability?
├─ Yes → Thread-safe needed?
│        ├─ Yes → Mutex<T> or RwLock<T>
│        └─ No → T: Copy? → Cell<T> : RefCell<T>
└─ No → Use &mut T

Resource Lifecycle (RAII)

// RAII Guard: cleanup on drop
struct FileGuard { path: PathBuf, _handle: File }

impl Drop for FileGuard {
    fn drop(&mut self) {
        let _ = std::fs::remove_file(&self.path);
    }
}

// Lazy Singleton (modern Rust — no lazy_static!)
use std::sync::OnceLock;

static CONFIG: OnceLock<Config> = OnceLock::new();

fn get_config() -> &'static Config {
    CONFIG.get_or_init(|| Config::load().expect("config required"))
}

Generics & Trait Objects

Static vs Dynamic Dispatch

When to Choose

Object Safety

A trait is object-safe if it:

• Doesn’t have Self: Sized bound
• Doesn’t return Self
• Doesn’t have generic methods
• Uses where Self: Sized for non-object-safe methods

// Static dispatch
fn process(x: impl Display) { }
fn process<T: Display>(x: T) { }

// Dynamic dispatch
fn process(x: &dyn Display) { }
fn process(x: Box<dyn Display>) { }

Documentation

Naming & Style

Naming: snake_case (fn/var), CamelCase (type), SCREAMING_CASE (const)
Format: rustfmt (just use it)
Docs: /// for public items, //! for module docs

Library Resilience

Logging

Static Verification

Recommended Cargo.toml lints:

[lints.rust]
missing_debug_implementations = "warn"
redundant_imports = "warn"
unsafe_op_in_unsafe_fn = "warn"
unused_lifetimes = "warn"

[lints.clippy]
cargo = { level = "warn", priority = -1 }
pedantic = { level = "warn", priority = -1 }
correctness = { level = "warn", priority = -1 }
perf = { level = "warn", priority = -1 }
style = { level = "warn", priority = -1 }
suspicious = { level = "warn", priority = -1 }
undocumented_unsafe_blocks = "warn"

Anti-Pattern Quick Reference

Build & Deploy

Always Use Makefile

Before running cargo build or any build command, check if a Makefile exists. If it does, use it — the Makefile encodes project-specific build steps (embedding assets, setting flags, post-build hooks) that raw commands miss.

Permissions & Ownership

Before building or deploying, check file permissions and ownership. Fix to match the project majority with stat -c '%U:%G' * | sort | uniq -c | sort -rn | head -5, then chown -R <user>:<group> . if needed.

Temporary Files

Exception: If project instructions specify a different temp location, follow those.

Test File Placement

Resources

• Ecosystem Integration & Mental Models — Standard crate choices, language interop, crate selection criteria, deprecated-to-modern replacements, ownership analogies, and common misconceptions.
• Domain Modeling — DDD-to-Rust pattern mapping (entities, aggregates, value objects, repositories), code examples, and common domain modeling mistakes.