rust

Rust Language Idioms

Work with the language, not against it. Embrace ownership, the borrow checker, and the type system.

---

Core Values

• Safety: Lean on the compiler's guarantees. Avoid unsafe unless absolutely necessary.
• Memory Efficiency: Zero-cost abstractions. Avoid unnecessary allocations.
• Ergonomics: APIs should be intuitive and hard to misuse.

---

API Design

Naming Conventions

Prefix	Semantics	Cost	Example
as_	Borrowed view, no allocation	Cheap	as_ref(), as_slice()
to_	Creates new owned value	Expensive	to_string(), to_vec()
into_	Consumes self, transforms	Cheap	into_iter(), into_inner()

Argument Flexibility

Accept generic bounds instead of concrete types:

// ❌ Inflexible
fn read_file(path: &PathBuf) -> Result<String>

// ✅ Accepts &str, String, PathBuf, &Path
fn read_file(path: impl AsRef<Path>) -> Result<String>

Common patterns:

• impl AsRef<Path> — for paths
• impl AsRef<str> — for string-like types
• impl Into<String> — when ownership is needed

Constructors

• Simple: T::new() for basic instantiation
• Configured: T::with_capacity(n) for single-option variants
• Complex: Use the Builder pattern for 3+ optional fields

let config = ConfigBuilder::new()
    .port(8080)
    .timeout(Duration::from_secs(30))
    .build()?;

Monomorphization Control

For widely-used generic functions, consider splitting:

// Public generic wrapper (thin)
pub fn process(path: impl AsRef<Path>) -> Result<()> {
    process_inner(path.as_ref())
}

// Private concrete implementation (bulk of logic)
fn process_inner(path: &Path) -> Result<()> {
    // ...
}

This reduces binary bloat and compile times.

---

Error Handling

The ? Operator