220-rust

Rust Programming Best Practices

Audience: engineers writing and reviewing Rust code Goal: Memory-safe, performant, idiomatic Rust following community best practices

Rust Philosophy (Core Principles)

Core Principles:

• "Memory safety without garbage collection" - Ownership system prevents memory errors at compile time
• "Zero-cost abstractions" - High-level code compiles to efficient low-level code
• "Fearless concurrency" - Type system prevents data races at compile time
• "Explicit over implicit" - No hidden allocations, no magic, everything is explicit
• "Compile-time guarantees" - If it compiles, it's correct (memory safety, thread safety)
• "Performance by default" - Fast, predictable performance without optimization flags
• "Composition over inheritance" - Traits and generics enable flexible design
• "Fail fast, fail clearly" - Use Result and Option, avoid panics in production

Applying Rust Principles:

// BAD: Unsafe, implicit, error-prone
fn process_data(data: Vec<i32>) -> i32 {
    let mut sum = 0;
    for i in 0..data.len() {
        sum += data[i];  // Potential index out of bounds
    }
    sum
}

// GOOD: Safe, explicit, idiomatic
fn process_data(data: &[i32]) -> i32 {
    data.iter().sum()  // Iterator is safe, explicit, efficient
}

// EXCELLENT: Type-safe, error handling
fn process_data(data: &[i32]) -> Result<i32, ProcessingError> {
    if data.is_empty() {
        return Err(ProcessingError::EmptyInput);
    }
    Ok(data.iter().sum())
}

Guiding Principles

1. Ownership & Borrowing: Master Rust's ownership system for memory safety
2. Zero-Cost Abstractions: Write high-level code without runtime overhead
3. Error Handling: Use Result and Option explicitly, avoid panics
4. Fearless Concurrency: Leverage Rust's type system for safe concurrency
5. Idiomatic Rust: Follow community conventions (rustfmt, clippy)

Public API Documentation (MUST)

• Use //! for crate and module documentation and /// for public items.
• Document public library APIs without restating types already visible in signatures or documenting obvious private helpers.
• Document caller-relevant errors, panics, ownership, borrowing, mutation, blocking, cancellation, side effects, thread safety, and resource lifecycle.
• Use # Examples, # Errors, and # Panics when applicable. Every public unsafe API MUST include # Safety.
• Every unsafe block MUST have a nearby // SAFETY: comment that states the invariant being upheld.
• Keep intra-doc links and doctests compiling. Run cargo test --doc, build docs with warnings denied, and run Clippy with warnings denied in CI.