# Rust Coding Conventions > Rust coding conventions covering error handling, naming, module organization, formatting, and testing. Load before writing, reviewing, or refactoring Rust code. Use when this capability is needed. - Skill: `tomevault-io/rust-coding-conventions` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/rust-coding-conventions` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/rust-coding-conventions/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/rust-coding-conventions --- # Rust Coding Conventions Read this skill before writing, reviewing, or refactoring Rust code in this project. It covers error handling, naming, module organization, formatting, testing, and more. --- ## Rust Coding Conventions **General Principles:** - Follow standard Rust conventions (use `rustfmt` and `clippy`) - Use idiomatic Rust patterns throughout - Prefer `Result` for error handling over panics - Apply RAII principles through Rust's ownership system - Use const-correctness via immutable references (`&`) - Write self-documenting code with clear naming and structure - Leverage the type system for compile-time safety - Keep functions focused and modular **Error Handling:** - Use `Result` for all fallible operations - Define a project-wide `Result` type alias with unified error type: ```rust pub type Result = std::result::Result>; ``` - Use `?` operator for error propagation - Avoid `.unwrap()` in library code; only use in application entry points after proper error handling - Use `.ok_or_else()` or `.ok_or()` to convert `Option` to `Result` with meaningful error messages - Provide context when returning errors: `Err(format!("Failed to download {}: {}", url, e).into())` - Never panic in library code unless documenting preconditions with `#[panic]` doc comments **Comparison and Conditional Expressions:** - Always use explicit boolean comparisons for clarity and consistency - Use `== true` and `== false` instead of bare conditionals or negation - Examples: - ✅ Correct: `if condition == true`, `if value == false` - ❌ Incorrect: `if condition`, `if !value` - Exception: Direct variable tests in control flow are allowed when clearly intentional - Apply to all boolean comparisons including `Option` and `Result` checks - Use explicit comparisons with `None`: `if option_value.is_none() == true` or `if option_value == None` - Allow clippy warnings for explicit boolean comparisons with project-level configuration **Module Organization:** - Use module structure to organize code by functionality - One public struct or major component per file - Related utility functions in dedicated `utils.rs` - Module declaration order in `lib.rs`: 1. Private module declarations (`mod`) 2. Public re-exports (`pub use`) 3. Type aliases - Example: ```rust mod template_manager; mod utils; pub use template_manager::TemplateManager; pub use utils::copy_dir_all; pub type Result = std::result::Result>; ``` **Functions and Methods:** - Document all public APIs with doc comments (`///`) - Use doc comment structure: - Brief one-line description (no explicit `# Description` header) - Longer explanation if needed (separated by blank line) - `# Arguments` section for parameters - `# Returns` section for return values (when non-obvious) - `# Errors` section for fallible functions - `# Examples` section when helpful - `# Panics` section if function can panic - Example: ```rust /// Creates a new TemplateManager instance /// /// Initializes paths to local data and cache directories using the `dirs` crate. /// Templates are stored in the local data directory and backups in the cache directory. /// /// # Errors /// /// Returns an error if the local data directory cannot be determined pub fn new() -> Result ``` - Pass by reference (`&`) for complex types, by value for `Copy` types - Use immutable references (`&`) unless mutation is required (`&mut`) - Keep function signatures on one line when under max width (167 chars) - Private helper functions should have single-line doc comments when logic is non-trivial **Structs and Types:** - Use clear, descriptive names for all types - Define fields in logical grouping order - Document struct purpose and usage with doc comments - Example: ```rust /// Manages template files for coding agent instructions /// /// The `TemplateManager` handles all operations related to template storage, /// verification, backup, and synchronization. Templates are stored in the /// local data directory and backed up to the cache directory before modifications. pub struct TemplateManager { config_dir: PathBuf, cache_dir: PathBuf } ``` - Use `#[derive]` for common traits when appropriate - Implement `Default` for structs with sensible defaults - Group related structs together in the same file when tightly coupled **Naming Conventions:** - Types (structs, enums, traits): Upper PascalCase (e.g., `TemplateManager`, `FileMapping`, `Result`) - Functions/methods: snake_case (e.g., `download_file`, `create_backup`, `load_template_config`) - Variables and function parameters: snake_case (e.g., `config_dir`, `source_path`, `file_name`) - Constants: UPPER_SNAKE_CASE (e.g., `MAX_WIDTH`, `DEFAULT_TIMEOUT`) - Type parameters: Single uppercase letter or PascalCase (e.g., `T`, `E`, `Error`) - Lifetimes: Short lowercase names (e.g., `'a`, `'static`) - Module names: snake_case (e.g., `template_manager`, `utils`) **Enums and Pattern Matching:** - Use descriptive variant names in PascalCase - Derive common traits when appropriate - Use `#[derive(Debug)]` for all types when possible for better error messages - Use exhaustive pattern matching; avoid `_ =>` catch-alls when possible - Use `if let` for single-pattern matching - Use `match` for multiple patterns or when you need exhaustiveness checking - Use `let...else` for early returns with single pattern: ```rust let Some(value) = option else { return Err("Missing value".into()); }; ``` - Prefer `Option` over sentinel enum variants. Do not add `Invalid`, `Unknown`, or `None` variants to an enum solely to avoid wrapping it in `Option`. `Option` is niche-optimized (zero runtime cost for most enums) and forces callers to handle absence at compile time, whereas sentinel variants move that guarantee to a runtime convention and pollute every match site with a defensive arm. - ❌ Incorrect: `enum Color { Invalid, Red, Green, Blue }` returned from a parser - ✅ Correct: `enum Color { Red, Green, Blue }` with `Option` at the boundary - Exception: when "unknown" is a meaningful domain state — e.g. forward-compatible protocol parsing where unrecognized variants must round-trip — model it explicitly (`HttpVersion::Unknown(String)`). This is "modeling the domain accurately," not "avoiding `Option`." **CLI Design with clap:** - Use clap's derive API for argument parsing - Define main CLI struct with `#[derive(Parser)]` - Use `#[derive(Subcommand)]` for command structure - Add helpful descriptions with `#[command]` attributes - Example: ```rust #[derive(Parser)] #[command(name = "my-app")] #[command(about = "A manager for coding agent instruction files", long_about = None)] struct Cli { #[command(subcommand)] command: Commands } ``` - Use clear, descriptive field names that match CLI conventions - Provide defaults with `#[arg(default_value = "...")]` - Add documentation comments to show in `--help` output **Formatting Configuration (.rustfmt.toml):** - Use project-specific rustfmt configuration for consistency - Key formatting rules: - `max_width = 167` - Allow longer lines for readability - `brace_style = "AlwaysNextLine"` - Opening braces on new lines - `control_brace_style = "AlwaysNextLine"` - Consistent brace placement - `trailing_comma = "Never"` - No trailing commas - `edition = "2024"` - Use latest Rust edition - `tab_spaces = 4` - Standard indentation - `imports_granularity = "Crate"` - Group imports by crate - `group_imports = "StdExternalCrate"` - Organize imports logically - Run `cargo fmt` before committing code - Configure editor to format on save **Imports and Dependencies:** - Group imports in order: 1. Standard library (`std::`) 2. External crates (alphabetically) 3. Project modules (`crate::`) - Use explicit imports over glob imports - Example: ```rust use std::{ fs, io::{self, Write}, path::{Path, PathBuf} }; use chrono::{DateTime, Utc}; use owo_colors::OwoColorize; use serde::{Deserialize, Serialize}; use crate::{Result, utils::copy_dir_all}; ``` - Re-export commonly used items from `lib.rs` for convenience **Conditional Compilation and Features:** - Use feature flags for optional functionality - Document feature requirements in doc comments - Use `#[cfg(feature = "...")]` for conditional code - Specify features in `Cargo.toml` dependencies when needed: ```toml reqwest = { version = "0.12", features = ["blocking", "json"] } ``` **Testing:** - Write unit tests alongside implementation in the same file - Use `#[cfg(test)]` module for tests - Name test functions descriptively: `test__` - Use `assert!`, `assert_eq!`, `assert_ne!` macros - Test both success and error cases - Example: ```rust #[cfg(test)] mod tests { use super::*; #[test] fn test_parse_github_url_valid() { // Test implementation } } ``` **Comments and Documentation:** - Use `///` for public API documentation (appears in generated docs) - Use `//!` for module-level documentation at file top - Use `//` for implementation comments and explanations - Document the "why" not the "what" in implementation comments - Keep comments up-to-date with code changes - Use full sentences with proper punctuation in doc comments - Example: ```rust //! Template management functionality for my-app /// Creates a timestamped backup of a directory /// /// Backups are stored in the cache directory with timestamp: `backups/YYYY-MM-DD_HH_MM_SS/` fn create_backup(&self, source_dir: &Path) -> Result<()> { // Skip backup if source doesn't exist if source_dir.exists() == false { return Ok(()); } // ... rest of implementation } ``` **Linting Configuration:** - Allow specific clippy lints when project style differs from defaults - Configure in `Cargo.toml`: ```toml [lints.clippy] bool_comparison = "allow" ``` - Can also use module-level attributes: ```rust #![allow(clippy::bool_comparison)] ``` - Document reasoning for lint exceptions **File Organization:** - Entry point: `src/main.rs` (minimal, delegates to library) - Library API: `src/lib.rs` (public interface) - Implementation: Feature modules in `src/` - Keep `main.rs` focused on CLI handling and error reporting - Put business logic in library modules for reusability - Example structure: ```text src/ ├── main.rs # CLI entry point ├── lib.rs # Public API ├── template_manager.rs # Core functionality └── utils.rs # Shared utilities ``` **Best Practices:** - Use `std::env::current_dir()` over hardcoding paths - Use `Path` and `PathBuf` for filesystem paths - Leverage `std::io::Write` trait for flushing output buffers - Use `owo-colors` or similar crate for terminal output styling - Use platform-appropriate paths via `dirs` crate (prefer over `$HOME` env var) - Implement `flush()` when printing without newline for immediate output: ```rust print!("{} Processing... ", "→".blue()); io::stdout().flush()?; ``` - Use early returns to reduce nesting depth - Prefer iterators and functional patterns over loops when clear **Error Messages:** - Use colored output for user-facing messages (owo-colors) - Format: `"{} {}", symbol.color(), message.color()` - Symbols: `✓` (success/green), `✗` (error/red), `→` (info/blue), `!` (warning/yellow), `?` (prompt/yellow) - Provide actionable error messages - Include file paths and operation details in errors - Example: ```rust println!("{} Creating backup in {}", "→".blue(), backup_dir.display().to_string().yellow()); eprintln!("{} Failed to download {}: {}", "✗".red(), url, error.to_string().red()); ``` **Version and Edition:** - Use Rust 2024 edition for latest language features - Specify in `Cargo.toml`: ```toml [package] edition = "2024" ``` - Keep dependencies up-to-date but specify versions explicitly - Use semantic versioning in package version **Code Review Checklist:** - [ ] All public APIs have doc comments - [ ] Error handling uses `Result` consistently - [ ] No `.unwrap()` calls in library code - [ ] Explicit boolean comparisons used throughout - [ ] Code formatted with `cargo fmt` - [ ] No clippy warnings (or explicitly allowed with reasoning) - [ ] Tests pass with `cargo test` - [ ] Code builds in both debug and release modes - [ ] Imports organized and minimal - [ ] Functions are focused and modular --- > Source: [heikopanjas/slopctl](https://github.com/heikopanjas/slopctl) — distributed by [TomeVault](https://tomevault.io).