38 lines
1.9 KiB
Markdown
38 lines
1.9 KiB
Markdown
# 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.
|