Rust Coding Standards

Rust Coding Standards

A comprehensive collection of Rust coding standards and best practices, adapted from the leonardomso/rust-skills catalog (MIT licensed — see NOTICE.md) for AI agents and LLMs to generate idiomatic, safe, and performant Rust code.

Categories

Async Programming [HIGH]

Correct, non-blocking use of async/await, the Tokio runtime, channels, and cancellation.

Type Safety [HIGH]

Encode invariants in the type system so invalid states become unrepresentable.

Serialization (Serde) [HIGH]

Serde patterns for robust, forward- and backward-compatible wire formats.

Observability [HIGH]

Structured logging, tracing, and metrics for diagnosing production behavior.

Unsafe Rust [HIGH]

Minimize, document, and verify the unsafe code that upholds Rust's safety guarantees.

Numeric Types [HIGH]

Overflow-safe arithmetic and correct numeric conversions.

Concurrency [HIGH]

Safe, efficient shared-state concurrency outside of async.

API Design [MEDIUM]

Public interface conventions that make crates predictable and hard to misuse.

Memory Management [MEDIUM]

Allocation, layout, and lifetime patterns that cut memory pressure and copies.

Naming [MEDIUM]

Naming conventions that keep Rust APIs idiomatic and self-documenting.

Anti-Patterns [MEDIUM]

Recognize and avoid common mistakes that compile cleanly but degrade correctness or performance.

Performance [MEDIUM]

General optimization patterns for CPU- and allocation-bound code.

Error Handling [MEDIUM]

Fallible-value patterns that keep errors typed, propagated, and actionable.

Ownership & Borrowing [MEDIUM]

Work with the borrow checker instead of against it.

Macros [MEDIUM]

Declarative and procedural macro patterns that stay hygienic and debuggable.

Traits [MEDIUM]

Trait design choices that balance flexibility, dispatch cost, and coherence.

Closures [MEDIUM]

Closure capture and trait-bound choices for callback-heavy code.

Pattern Matching [MEDIUM]

Exhaustive, expressive matching over enums and data structures.

Collections [MEDIUM]

Choose and use the standard collection types correctly.

Const & Compile-Time [MEDIUM]

Move work to compile time with const generics, const fn, and static evaluation.

Conversions [MEDIUM]

Type conversion traits that make transformations explicit and fallible where needed.

Documentation [LOW]

Rustdoc conventions that keep public APIs discoverable and example code compilable.

Compiler Optimization [LOW]

Codegen and build-level tuning: inlining hints, LTO, PGO, and target features.

Quick Reference

Async Programming

// Many concurrent connections: keep the default multi-threaded runtime,
// and size worker_threads deliberately rather than accepting whatever
// the host's core count happens to be.
#[tokio::main(worker_threads = 4)]
async fn main() {
    let client = Client::new();
    client.run().await;
}

Type Safety

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct UserId(pub u64);

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct PostId(pub u64);

fn get_user_posts(user_id: UserId, post_id: PostId) -> Vec<Post> {
    todo!()
}

Serialization (Serde)

use serde::{Serialize, Deserialize};

#[derive(Serialize, Deserialize, Debug)]
#[serde(deny_unknown_fields)]
struct ServerConfig {
    host: String,
    port: u16,
    timeout_secs: u64,
}

// A typo like "timout_secs" is now a hard, actionable deserialize error
// instead of a silently-ignored field.

Observability

use tracing::info;

fn handle_login(id: u64) {
    info!(user.id = %id, "user logged in"); // filterable, structured, levelled
}

fn main() {
    tracing_subscriber::fmt::init(); // subscriber setup belongs in the binary
    handle_login(42);
}

Unsafe Rust

/// Returns the byte at `ptr + offset`.
///
/// # Safety
///
/// - `ptr` must be valid for reads for at least `offset + 1` bytes.
pub unsafe fn read_at(ptr: *const u8, offset: usize) -> u8 {
    // SAFETY: caller guarantees ptr is valid for at least offset + 1 bytes,
    // so ptr.add(offset) is in bounds and dereferenceable.
    unsafe { *ptr.add(offset) }
}

Numeric Types

// checked_add: returns None on overflow -- propagate or handle the error
fn add_score(current: u32, delta: u32) -> Option<u32> {
    current.checked_add(delta)
}

// saturating_add: clamps at the type's bound, no error path needed
fn increment_saturating(c: u8) -> u8 {
    c.saturating_add(1)
}

Concurrency

use std::thread;

fn parallel_sum(data: &[i64]) -> i64 {
    let mid = data.len() / 2;
    let (left, right) = data.split_at(mid);

    thread::scope(|s| {
        let h1 = s.spawn(|| left.iter().sum::<i64>());
        let h2 = s.spawn(|| right.iter().sum::<i64>());
        h1.join().unwrap() + h2.join().unwrap()
    })
}

API Design

#[derive(Default)]
#[must_use = "builders do nothing unless you call build()"]
pub struct ClientBuilder {
    base_url: Option<String>,
    timeout: Option<Duration>,
}

impl ClientBuilder {
    pub fn base_url(mut self, url: impl Into<String>) -> Self {
        self.base_url = Some(url.into());
        self
    }

    pub fn build(self) -> Result<Client, BuilderError> {
        let base_url = self.base_url.ok_or(BuilderError::MissingBaseUrl)?;
        Ok(Client { base_url, timeout: self.timeout.unwrap_or(Duration::from_secs(30)) })
    }
}

// Usage -- clear and self-documenting
let client = ClientBuilder::default().base_url("https://api.example.com").build()?;

Memory Management

// Pre-allocate the exact size: zero reallocations
let mut results = Vec::with_capacity(1000);
for i in 0..1000 {
    results.push(process(i));
}

// Or let collect() use the iterator's size hint automatically
let results: Vec<_> = (0..1000).map(process).collect();

Naming

fn fetch_user_profile(user_id: u64) -> UserProfile {
    let last_login = user_id;
    todo!()
}

mod user_service;
mod http_client;

Anti-Patterns

fn summarize(report: &Report) {
    log_report(report);          // read-only, borrow is enough
    if report.is_valid() {       // read-only, no clone needed
        archive(report.clone()); // clone only where ownership is genuinely required
    }
}

Performance

use std::collections::HashMap;

fn increment(map: &mut HashMap<String, u32>, key: String) {
    *map.entry(key).or_insert(0) += 1; // single lookup either way
}

Error Handling

fn load_config() -> Result<Config, Error> {
    let content = std::fs::read_to_string("config.toml")?;
    let config = toml::from_str(&content)?;
    Ok(config)
}

Ownership & Borrowing

fn process(data: &str) { // Accept &str, more flexible
    println!("{}", data); // No allocation needed
}

fn count_words(text: &str) -> usize {
    text.split_whitespace().count() // Just borrow
}

Macros

#[macro_export]
macro_rules! log {
    ($val:expr) => {
        // $crate always expands to the crate that defined this macro
        $crate::log_value(&format!("{:?}", $val));
    };
}

// Hygiene for local bindings: `tmp` inside the macro never clashes with the caller's `tmp`
macro_rules! swap {
    ($a:expr, $b:expr) => {{
        let tmp = $a;
        $a = $b;
        $b = tmp;
    }};
}

Traits

use std::fmt;

trait Describe {
    fn describe(&self) -> String;
}

// One impl covers every T: Display, mirroring std's ToString.
impl<T: fmt::Display> Describe for T {
    fn describe(&self) -> String {
        format!("{self} ({})", std::any::type_name::<T>())
    }
}

Closures

// Call exactly once -- accept FnOnce, the widest possible bound
fn run_once<F: FnOnce() -> String>(f: F) -> String {
    f()
}

// Call multiple times, closure may mutate its captures -- accept FnMut
fn retry<F: FnMut() -> bool>(mut f: F, attempts: usize) -> bool {
    (0..attempts).any(|_| f())
}

Pattern Matching

fn process(input: Option<String>) -> Option<u32> {
    let Some(s) = input else { return None; };
    let Ok(n) = s.trim().parse::<u32>() else { return None; };
    if n == 0 {
        return None;
    }
    Some(n * 2)
}

Collections

use std::collections::HashMap;

// HashMap: default, fast, order irrelevant
fn total_scores<'a>(records: &[(&'a str, u32)]) -> HashMap<&'a str, u32> {
    let mut scores: HashMap<&'a str, u32> = HashMap::new();
    for &(name, score) in records {
        *scores.entry(name).or_insert(0) += score;
    }
    scores
}

Const & Compile-Time

const fn header_len() -> usize {
    4
}

// Usable as an array length -- evaluated at compile time
let buf = [0u8; header_len()];

const fn align_up(n: usize, align: usize) -> usize {
    (n + align - 1) & !(align - 1)
}

const ALIGNED: usize = align_up(13, 8); // 16, computed once, at compile time

Conversions

#[derive(Debug)]
struct Port(u16);

impl TryFrom<u32> for Port {
    type Error = PortError;

    fn try_from(value: u32) -> Result<Self, Self::Error> {
        u16::try_from(value).map(Port).map_err(|_| PortError(value))
    }
}

fn accept_port(n: u32) -> Result<Port, PortError> {
    n.try_into() // standard idiom, works anywhere TryFrom<u32> is implemented
}

Documentation

/// Sends the request and parses the response.
///
/// # Errors
///
/// - [`HttpError::Timeout`] if the server doesn't respond within the configured timeout
/// - [`HttpError::InvalidUrl`] if `req`'s URL fails to parse
pub fn send(req: Request) -> Result<Response, HttpError> {
    // ...
}

Compiler Optimization

#[inline]
pub fn is_ascii_digit(b: u8) -> bool {
    b >= b'0' && b <= b'9'
}

See Also

• rust-testing - Test-writing best practices for Rust
• rust-tooling - clippy, rustfmt, and Cargo workspace/project-structure rules
• NOTICE - MIT attribution for content adapted from leonardomso/rust-skills