Rust Programming Style Guide

Quick reference for project-specific Rust conventions. Load reference files for detailed examples.

Code Style Quick Reference

String Creation

• •Use String::from("...") instead of "...".to_string()
• •Use String::new() instead of "".to_string()

Type Annotations

• •Always use postfix types (turbofish syntax)
• •❌ let foo: Vec<_> = items.collect()
• •✅ let foo = items.collect::<Vec<_>>()

Control Flow

Prefer let Some(value) = option else { ... } over .is_none() + .unwrap()

Array Indexing

Avoid array indexing. Use iterator methods: .enumerate(), .iter().map()

See references/indexing-patterns.md for detailed examples

Naming Conventions Quick Reference

Type Names: Avoid Stuttering

When a type is namespaced by its module, don't repeat context:

• •❌ storage::CasStorage or storage::DiskStorage — stutters "storage"
• •✅ storage::Disk — describes implementation (see courier/src/storage.rs:54)
• •❌ db::PostgresDatabase — stutters "database"
• •✅ db::Postgres — describes implementation (see courier/src/db.rs:29)

Enum Variants

Use single canonical variant with alias functions instead of separate variants for the same concept

See references/naming.md for complete guidelines

Function and Variable Names

• •Don't prefix test functions with test_
• •Don't use hungarian notation; prefer shadowing
• •❌: formats_str → ✅: formats

Import and Module Style

Imports

Prefer direct imports over fully qualified paths unless ambiguous:

// ✅ Prefer
use client::courier::v1::{Key, cache::ArtifactFile};
let key = Key::from_hex(&hex_string)?;

// ❌ Avoid
let key = client::courier::v1::Key::from_hex(&hex_string)?;

Module Structure

• •Do not use mod.rs. Always prefer my_module.rs + my_module/other_file.rs

String Formatting

Inline rust variables in format strings if possible:

• •✅ format!("Hello, {name}")
• •Use expressions when needed: format!("Hello, {}", user.name())

Development Workflow

Dependency Management

• •Use cargo add instead of manual Cargo.toml edits
• •Run cargo autoinherit after adding packages (if workspace uses inheritance)

Code Quality

• •Format code: make format (uses nightly rustfmt)
• •Run linter: make check
• •Auto-fix lints: make check-fix
• •Pre-commit checks: make precommit (runs machete-fix, autoinherit, check-fix, format, sqlx-prepare)
• •Prefer Itertools::sorted over Vec::sort for iterator chains

I/O Operations

Prefer streaming over buffered by default. Use traits: AsyncRead, AsyncWrite, Read, Write

Error Handling

• •Use color-eyre for errors and reporting
• •Only panic for invariant violations or in tests
• •Prefer returning Result for recoverable errors

Documentation

Don't bold bullet points in markdown:

• •❌ - **Hook**: message
• •✅ - Hook: message

Avoid "space dash space" pattern in prose, use colon instead:

• •❌ "All commands work the same way - do x then y"
• •✅ "All commands work the same way: do x then y"

Reference Files

Load these for detailed examples and patterns:

• •references/indexing-patterns.md - Array indexing alternatives with iterator methods
• •references/naming.md - Complete naming conventions with examples
• •references/control-flow.md - Control flow patterns and examples

When to Use This Skill

Invoke when:

• •Writing new Rust code
• •Reviewing code for style violations
• •Refactoring existing Rust code
• •Onboarding to project conventions