Rust

# Rust Coding Conventions and Best Practices

Follow idiomatic Rust practices and community standards when writing Rust code.

These instructions are based on [The Rust Book](https://doc.rust-lang.org/book/), [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/), [RFC 430 naming conventions](https://github.com/rust-lang/rfcs/blob/master/text/0430-finalizing-naming-conventions.md), and the broader Rust community at [users.rust-lang.org](https://users.rust-lang.org).

General Instructions

- Always prioritize readability, safety, and maintainability.

- Use strong typing and leverage Rust's ownership system for memory safety.

- Break down complex functions into smaller, more manageable functions.

- For algorithm-related code, include explanations of the approach used.

- Write code with good maintainability practices, including comments on why certain design decisions were made.

- Handle errors gracefully using `Result<T, E>` and provide meaningful error messages.

- For external dependencies, mention their usage and purpose in documentation.

- Use consistent naming conventions following [RFC 430](https://github.com/rust-lang/rfcs/blob/master/text/0430-finalizing-naming-conventions.md).

- Write idiomatic, safe, and efficient Rust code that follows the borrow checker's rules.

- Ensure code compiles without warnings.

Patterns to Follow

- Use modules (`mod`) and public interfaces (`pub`) to encapsulate logic.

- Handle errors properly using `?`, `match`, or `if let`.

- Use `serde` for serialization and `thiserror` or `anyhow` for custom errors.

- Implement traits to abstract services or external dependencies.

- Structure async code using `async/await` and `tokio` or `async-std`.

- Prefer enums over flags and states for type safety.

- Use builders for complex object creation.

- Split binary and library code (`main.rs` vs `lib.rs`) for testability and reuse.

- Use `rayon` for data parallelism and CPU-bound tasks.

- Use iterators instead of index-based loops as they're often faster and safer.

- Use `&str` instead of `String` for function parameters when you don't need ownership.

- Prefer borrowing and zero-copy operations to avoid unnecessary allocations.

Ownership, Borrowing, and Lifetimes

- Prefer borrowing (`&T`) over cloning unless ownership transfer is necessary.

- Use `&mut T` when you need to modify borrowed data.

- Explicitly annotate lifetimes when the compiler cannot infer them.

- Use `Rc<T>` for single-threaded reference counting and `Arc<T>` for thread-safe reference counting.

- Use `RefCell<T>` for interior mutability in single-threaded contexts and `Mutex<T>` or `RwLock<T>` for multi-threaded contexts.

Patterns to Avoid

- Don't use `unwrap()` or `expect()` unless absolutely necessary—prefer proper error handling.

- Avoid panics in library code—return `Result` instead.

- Don't rely on global mutable state—use dependency injection or thread-safe containers.

- Avoid deeply nested logic—refactor with functions or combinators.

- Don't ignore warnings—treat them as errors during CI.

- Avoid `unsafe` unless required and fully documented.

- Don't overuse `clone()`, use borrowing instead of cloning unless ownership transfer is needed.

- Avoid premature `collect()`, keep iterators lazy until you actually need the collection.

- Avoid unnecessary allocations—prefer borrowing and zero-copy operations.

Code Style and Formatting

- Follow the Rust Style Guide and use `rustfmt` for automatic formatting.

- Keep lines under 100 characters when possible.

- Place function and struct documentation immediately before the item using `///`.

- Use `cargo clippy` to catch common mistakes and enforce best practices.

Error Handling

- Use `Result<T, E>` for recoverable errors and `panic!` only for unrecoverable errors.

- Prefer `?` operator over `unwrap()` or `expect()` for error propagation.

- Create custom error types using `thiserror` or implement `std::error::Error`.

- Use `Option<T>` for values that may or