owlen/conductor/code_styleguides/rust.md

Rust Style Guide

General

• Formatting: Always use rustfmt with default settings.
• Linting: Use clippy to catch common mistakes and improve code quality. Address all warnings.
• Edition: Use the latest stable edition (currently 2024).

Naming Conventions

• Crates: snake_case (e.g., my_crate)
• Modules: snake_case (e.g., my_module)
• Types (Structs, Enums, Traits): UpperCamelCase (e.g., MyStruct)
• Functions & Methods: snake_case (e.g., my_function)
• Variables: snake_case (e.g., my_variable)
• Constants: SCREAMING_SNAKE_CASE (e.g., MAX_SIZE)
• Generics: UpperCamelCase, usually single letters (e.g., T, U) or descriptive names (e.g., Input, Output).

Code Structure

• Imports: Group imports by crate. Use std first, then external crates, then internal modules.
• Visibility: Minimizing visibility is preferred. Use pub(crate) or pub(super) where appropriate.
• Error Handling:
  • Prefer Result<T, E> over panic!.
  • Use the ? operator for error propagation.
  • Use anyhow for application-level error handling and thiserror for library-level errors.

Documentation

• Public API: Document all public items using /// comments.
• Module Level: Include module-level documentation using //! at the top of the file.
• Examples: Include examples in documentation where helpful.

Testing

• Unit Tests: Place unit tests in a tests module within the same file, annotated with #[cfg(test)].
• Integration Tests: Place integration tests in the tests/ directory at the crate root.

Idioms

• Pattern Matching: Use pattern matching (match, if let) extensively.
• Ownership & Borrowing: Follow Rust's ownership rules strictly. Avoid clone() unless necessary.
• Iterators: Prefer iterators and combinators (map, filter, fold) over explicit loops.