rust-development

Rust Development Guidelines

Directives for Rust development. Apply when working with .rs files or Cargo.toml.

---

Ownership and Borrowing

• Prefer borrowing over moving when the caller needs the value afterwards; use &T or &mut T.
• Move by default when transferring ownership; assignment moves for non-Copy types.
• Clone only when necessary — cloning is explicit and can be expensive; prefer references.
• Use &str over &String for function parameters when you only need to read.
• Return owned values from functions when the caller should own the result; avoid returning references to local data.
• Borrow mutably (&mut T) only when you need to modify; avoid overlapping mutable borrows.
• Use into_iter() when consuming a collection; use iter() when you need references.
• Do not return references to temporary or stack-allocated data.

let s1 = String::from("hello");
let s2 = s1;   // move; s1 invalid
let s3 = &s2;  // borrow; s2 still valid

---

Lifetimes

• Add explicit lifetimes when the compiler cannot infer them (e.g. function returns a reference derived from parameters).
• Rely on elision when the rules apply: one input ref → output ref gets that lifetime; one &self/&mut self → output ref gets that lifetime.
• Use 'static only for data that lives for the whole program; avoid for general-purpose APIs.
• Structs holding references need lifetime parameters: struct Excerpt<'a> { part: &'a str }.
• Prefer owned types when lifetimes make the API complex; sometimes String is simpler than &str in public APIs.

---

Smart Pointers

• Box<T> — Single ownership, heap allocation; use for recursive types, large values, or trait objects.
• Rc<T> — Shared ownership, single-threaded; use when multiple owners need the same value (e.g. graphs, shared config).
• Arc<T> — Thread-safe shared ownership; use when sharing across threads; pair with Mutex or RwLock for mutability.
• Avoid Rc/Arc when possible — they add overhead; prefer borrowing or owned values when ownership is clear.