majiayu000 Rust Systems Programming Best Practices
Comprehensive Rust patterns and style conventions for systems programming, containing 52 rules across 5 categories. Designed for systems programming, CLI tools, and performance-critical applications.
When to Apply
Reference these guidelines when:
- Writing new Rust code or modules
- Organizing Rust project structure
- Defining custom types, traits, or error handling
- Reviewing Rust code for style consistency
- Building systems tools, CLIs, or daemon processes
Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | Project Organization | HIGH | org- |
| 2 | Module Structure | HIGH | mod- |
| 3 | Naming Conventions | HIGH | name- |
| 4 | Type & Trait Patterns | HIGH | type- |
| 5 | Error Handling | HIGH | err- |
Quick Reference
1. Project Organization (HIGH)
org-cargo-workspace- Use Cargo Workspace for Multi-Crate Projectsorg-directory-naming- Use snake_case for All Directory Namesorg-binary-library-separation- Separate Binary and Library Cratesorg-feature-domain-grouping- Group Crates by Feature Domainorg-common-crate- Use Dedicated Common Crate for Shared Utilitiesorg-flat-crate-structure- Keep Crate Structure Flat
2. Module Structure (HIGH)
mod-explicit-declarations- Use Explicit Module Declarations in lib.rsmod-colocated-tests- Co-locate Tests as test.rs Filesmod-submodule-organization- Use mod.rs for Multi-File Modulesmod-types-errors-files- Separate Types and Errors into Dedicated Filesmod-reexport-pattern- Use pub use for Clean API Re-exportsmod-conditional-compilation- Use cfg Attributes for Conditional Modules
3. Naming Conventions (HIGH)
name-function-snake-case- Use snake_case for Functions and Methodsname-type-pascal-case- Use PascalCase for Typesname-constant-screaming- Use SCREAMING_SNAKE_CASE for Constantsname-getter-prefix- Prefix Getter Functions with get_name-boolean-predicates- Use is_, has_, should_ for Boolean Predicatesname-constructor-new- Use new for Constructorsname-conversion-to-from- Use to_ and from_ for Conversionsname-type-suffixes- Use Descriptive Suffixes for Type Specializationname-field-unit-suffixes- Include Unit Suffixes in Field Namesname-module-snake-case- Use snake_case for Module Namesname-generic-parameters- Use Descriptive or Single-Letter Generic Parametersname-lifetime-parameters- Use Single Lowercase Letters for Lifetimesname-test-files- Name Test Files as test.rs
4. Type & Trait Patterns (HIGH)
type-option-nullable-fields- Use Option for Nullable Fieldstype-standard-derives- Use Consistent Derive Order for Data Structstype-builder-pattern- Use Builder Pattern with Method Chainingtype-associated-types- Use Associated Types for Related Type Relationshipstype-phantom-data- Use PhantomData for Unused Generic Parameterstype-newtype-pattern- Use Newtype Pattern for Type Safetytype-enum-copy-simple- Derive Copy for Simple Enumstype-enum-variants- Use Enums for Type-Safe Variantstype-trait-impl-grouping- Group Related Trait Implementations Togethertype-bitflags- Use bitflags! for Type-Safe Bit Flagstype-operator-overload- Implement Operator Traits for Domain Typestype-public-fields- Use Public Fields for Data Structstype-async-trait- Use async_trait for Async Trait Methodstype-boxed-trait-objects- Use Box for Runtime Polymorphismtype-type-aliases- Use Type Aliases for Complex Generics
5. Error Handling (HIGH)
err-thiserror-enum- Use thiserror for Custom Error Typeserr-result-alias- Define Module-Local Result Type Aliaserr-path-context- Include Path Context in IO Errorserr-anyhow-context- Use context() and with_context() for Error Messageserr-bail-validation- Use bail! for Validation Failureserr-graceful-degradation- Use Graceful Degradation for Non-Critical Operationserr-panic-unrecoverable- Reserve panic! for Unrecoverable Situationserr-expect-message- Use expect() with Descriptive Messageserr-source-attribute- Use #[source] for Error Chainingerr-ok-or-else- Use ok_or_else for Expensive Error Constructionerr-two-tier-strategy- Use Two-Tier Error Strategy
How to Use
Read individual reference files for detailed explanations and code examples:
- Section definitions - Category structure and impact levels
- Rule template - Template for adding new rules
Full Compiled Document
For the complete guide with all rules expanded: AGENTS.md