name: rust-best-practices description: > Generic best practices, patterns, and style guidelines for writing Rust code in Fuchsia, incorporating the official Fuchsia Rust Rubric.

Rust Best Practices in Fuchsia

This guide outlines generic best practices, style conventions, and API design rules for writing Rust code in Fuchsia. It incorporates the official Fuchsia Rust Rubric (from docs/development/api/rust.md). For driver-specific practices, refer to the rust_driver_best_practices skill.

1. Naming and Style Conventions

  • Casing Conforms to Rust Idioms: Follow standard Rust naming casing. For example, CamelCase for types, snake_case for functions and variables, and SCREAMING_SNAKE_CASE for constants. See C-CASE.
  • Getter Names Avoid get_: Do not use the get_ prefix for getter methods. Use direct field names (e.g., rect.width() instead of rect.get_width()). See C-GETTER.
  • Ad-Hoc Conversions: Ad-hoc conversions follow standard prefix/suffix naming conventions:
    • as_: Cheap, reference-to-reference conversion (e.g., as_bytes()).
    • to_: Expensive, reference-to-value/owned conversion (e.g., to_str()).
    • into_: Consuming value-to-value conversion (e.g., into_vec()).
    • See C-CONV.
  • Iterator Methods & Type Names: Methods on collections that produce iterators should follow iter, iter_mut, into_iter. Iterator type names should match the methods that produce them (e.g., Iter, IterMut, IntoIter). See C-ITER and C-ITER-TY.
  • Consistent Word Order: Keep word ordering consistent across APIs (e.g. new_connection and open_connection, rather than mixing prefixes and suffixes). See C-WORD-ORDER.
  • Use Statements at Top: All use statements must be grouped together at the top of the file. Do not place use statements inline within functions or modules. This makes file dependencies clear and easy to find.
  • Avoid Long Namespaces: Use use statements to import symbols so that you can avoid long namespaced structs or methods in the code. This improves readability.
  • Descriptive Naming: Do not use shorthand or abbreviated names for variables, structs, or functions. Use complete, descriptive words.
  • Avoid allow_unused: Do not leave #[allow(unused)] or #[allow(dead_code)] in the final implementation. If a field is intentionally unused but must be held by a struct (like an async scope to keep it alive), prefix its name with an underscore (e.g., _scope).
  • Clean up AI-Targeted Comments: Analyze all comments before finalizing the code. Remove any comments that are targeted at the AI agent itself.
  • Associated vs. Free (Top-Level) Functions:
    • Keep a function as an associated function in the impl block if the type is important to the function's purpose (e.g., constructors returning Self or a Result/Option of Self).
    • Prefer associated functions when a free function's name would otherwise feel redundant by including the type name (e.g., favor Thing::does_what() over a free function named thing_does_what()).
    • Avoid overly strong preferences for free functions, as too many free functions create namespace noise.
    • Note that in Rust, the privacy boundary is the module (mod), not the type itself. Free functions inside the same module can access private fields of a struct just as easily as associated functions.
  • Use Constants, Not Magic Values: Avoid scattering hardcoded numeric literals throughout the code. Use descriptive const definitions at the top of the file or module for loop counts, timeout limits, array sizes, and configuration values.

2. Interoperability and Traits

  • Eagerly Implement Common Traits: Implement common standard library traits when appropriate. These include Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug, Display, and Default. See C-COMMON-TRAITS.
  • Standard Conversion Traits: Prefer using standard conversion traits like From, AsRef, and AsMut rather than custom methods where possible. Implementing From<A> for B automatically gives you Into<B> for A. See C-CONV-TRAITS.
  • Collections and Iterators: Custom collections should implement FromIterator and Extend to interact naturally with standard Rust iterators and .collect(). See C-COLLECT.
  • Data Serialization: Data structures representing external interfaces or configurations should implement Serde's Serialize and Deserialize traits. See C-SERDE.
  • Concurrency Safety: Types should be Send and Sync where possible. Ensure your design doesn't inadvertently block these traits unless thread unsafety is intended. See C-SEND-SYNC.
  • Meaningful Error Types: Error types should be meaningful, well-behaved, and implement std::error::Error. Avoid returning raw strings or generic error types unless prototyping. See C-GOOD-ERR.
  • Binary Number Formatting: If representing custom binary numbers or bit flags, provide formatting implementations for Hex, Octal, and Binary. See C-NUM-FMT.
  • Generic I/O Signatures: Generic reader/writer functions should take R: Read and W: Write by value, not by reference, to allow callers to pass owned readers/writers or standard wrappers. See C-RW-VALUE.

3. API and Type Design

  • Smart Pointers: Avoid adding inherent methods to smart pointers. All methods on a smart pointer should be accessed via trait implementations or associated functions to avoid shadowing methods on the inner type. See C-SMART-PTR.
  • Conversion Location: Conversions live on the most specific type involved. See C-CONV-SPECIFIC.
  • Clear Receivers: Functions with a clear primary receiver should be designed as methods taking self, &self, or &mut self. See C-METHOD.
  • No Out-Parameters: Functions should return their results directly (as single values, tuples, or structs) rather than using mutable out-parameters. See C-NO-OUT.
  • Unsurprising Operator Overloads: Overload operators only when the behavior is completely expected and matches standard conventions (e.g., overriding Add for a custom complex number type). See C-OVERLOAD.
  • Deref & DerefMut: Implement Deref and DerefMut ONLY for smart pointers. Do not use them for inheritance or code reuse. See C-DEREF.
  • Constructors: Constructors should be static, inherent methods (typically called new or with_...). See C-CTOR.
  • Flexibility and Performance:
    • Expose Intermediate Results: Expose intermediate results in your API where they can prevent duplicate work for callers. See C-INTERMEDIATE.
    • Caller Decides Allocation: Let the caller decide where to copy and place data (e.g., pass owned arguments or Cow rather than cloning internally). See C-CALLER-CONTROL.
    • Generic Parameters: Minimize assumptions about parameters by using generics (e.g., impl AsRef<str> instead of &str if appropriate). See C-GENERIC.
    • Object Safety: Design traits to be object-safe if they may be useful as a trait object. See C-OBJECT.
  • Type Safety and Encapsulation:
    • Newtypes for Static Distinction: Use the newtype pattern to provide static type distinctions (e.g., struct UserId(u64) rather than a plain u64). See C-NEWTYPE.
    • Arguments Convey Meaning: Use custom types or enums for arguments to convey precise meaning, instead of using boolean flag parameters or nested Option types. See C-CUSTOM-TYPE.
    • Sets of Flags: Use the bitflags crate to represent a set of flags, not enums or raw integers. See C-BITFLAG.
    • Builders for Complex Values: Use the builder pattern to construct complex values where there are many optional parameters. See C-BUILDER.
    • Sealed Traits: Use sealed traits if you want to define a trait but prevent downstream crates from implementing it. See C-SEALED.
    • Private Fields: Struct fields should be private by default to encapsulate implementation details. See C-STRUCT-PRIVATE.
    • Encapsulation: Use newtypes to encapsulate internal implementation details of complex types. See C-NEWTYPE-HIDE.
    • Derived Bounds: Do not duplicate derived trait bounds on struct definitions; place them on the impl blocks instead. See C-STRUCT-BOUNDS.

4. Concurrency and Async Patterns

  • spawn vs spawn_local:
    • Use scope.spawn() as the default when the task implements Send.
    • Use scope.spawn_local() when the task does not implement Send (e.g., it holds non-thread-safe types like Rc or RefCell).
  • Do Not Detach Tasks: Never use fuchsia_async::Task::spawn(...).detach();. Detaching tasks is considered bad style and can lead to resource leaks or silent task failures. Use scope.spawn(...); instead.
  • Mutex Preference: When a mutex is strictly necessary, prefer using fuchsia_sync::Mutex over std::sync::Mutex.

5. Macros

  • Evocative Input: The input syntax of a macro should be evocative of the output it produces. See C-EVOCATIVE.
  • Attribute Composition: Macros should compose well with attributes, ensuring that doc-comments and other attributes can be attached directly to generated items. See C-MACRO-ATTR.
  • Item Scope: Item macros should work anywhere that items are allowed (e.g., in modules, functions). See C-ANYWHERE.
  • Visibility: Item macros should support standard visibility specifiers (like pub, pub(crate)). See C-MACRO-VIS.
  • Type Flexibility: Macro type fragments should be flexible and allow for standard Rust types and lifetime bounds. See C-MACRO-TY.

6. Documentation & Rustdoc Guidelines

  • Crate-Level Docs: Crate-level documentation must be thorough and include examples of how to use the crate. See C-CRATE-DOC.

  • Item Examples: All public items should have a rustdoc example illustrating their usage. See C-EXAMPLE.

    [!NOTE] This guideline is not strictly enforced for targets building on Fuchsia until doctests are supported on Fuchsia targets.

  • Ergonomic Examples: Examples should use the ? operator, not try!, and not call unwrap or expect. See C-QUESTION-MARK.

  • Function Failure and Safety: Function docs must clearly document:

    • Error conditions under which the function returns Err.
    • Panic conditions (under what inputs or states the function will panic).
    • Safety considerations (preconditions required for unsafe functions). See C-FAILURE.
  • Prose Hyperlinks: Include hyperlinks to relevant types, methods, and concepts in rustdoc prose. See C-LINK.

  • Hide Implementation Details: Rustdoc should not show unhelpful internal implementation details. See C-HIDDEN.

7. Safety and Unsafe Code Rules

  • Error Handling: Avoid unwrap() and expect() which can panic the process. Use ok_or_else() or handle errors explicitly. If an error is truly unrecoverable, provide a context string explaining why it is safe to panic.

  • Arithmetic: Always use checked math operations (e.g., checked_add(), checked_mul()) on external or untrusted input to prevent overflows.

  • Fuchsia Unsafe Guidelines:

    [!IMPORTANT] Every unsafe block must have an accompanying justification. Safety justifications should begin with // SAFETY: and explain why the unsafe block is sound.

    • Format Requirements:
      • Must use // SAFETY: <why this unsafe operation is sound>
      • Do NOT use other formats like // Safety:, // [SAFETY], or lazy placeholders like // SAFETY: Trust me.
    • Soundness Explanation: Explain why the unsafe block is necessary and why the code inside is sound. If there are safe alternatives that appear suitable but cannot be used, document why they are not viable (e.g., performance).

    Do:

    // SAFETY: The `bytes` returned from our string builder are guaranteed to be
    // valid UTF-8. We used to call `from_utf8`, but this caused performance issues
    // with large inputs.
    let s = unsafe { String::from_utf8_unchecked(bytes) };
    

    Don't:

    // SAFETY: We shouldn't have to validate `bytes`, and the safe version is slow.
    let s = unsafe { String::from_utf8_unchecked(bytes) };
    
    • Unsafe Traits & Impls:

      • Unsafe traits must document safety considerations.
      • Unsafe trait implementations must be justified using the // SAFETY: comment pattern.
    • Always use unsafe Blocks in unsafe Functions:

      • unsafe functions are not considered unsafe contexts in Fuchsia. Unsafe operations must always be located inside an explicit unsafe block, even if they are in an unsafe function body.

    Do:

    unsafe fn clear_slice(ptr: *mut i32, len: usize) {
        assert!(len.checked_mul(mem::size_of::<i32>()).unwrap() < isize::MAX);
    
        // SAFETY:
        // - The caller has guaranteed that `ptr` points to `len` consecutive, valid
        //   i32s and that the data behind `ptr` is not simultaneously accessed.
        // - We asserted that the total size of the slice is less than isize::MAX.
        let slice = unsafe { slice::from_raw_parts_mut(ptr, len) };
        for x in slice.iter_mut() {
            *x = 0;
        }
    }
    

8. Dependability and Debuggability

  • Argument Validation: Functions validate their arguments and return early with an error or panic on invalid inputs before corrupting state. See C-VALIDATE.
  • Destructors Never Fail: Destructors (Drop implementations) should never fail or panic. See C-DTOR-FAIL.
  • Non-blocking Destructors: Destructors that may block the thread must have non-blocking alternatives. See C-DTOR-BLOCK.
  • Public Types Debuggability: All public types must implement Debug. See C-DEBUG.
  • Non-empty Debug Representation: The Debug representation should never be empty. See C-DEBUG-NONEMPTY.

9. Testing Idioms

  • Test Macro: Use #[fuchsia::test] instead of #[test]. It natively supports async tests and logging out of the box.
  • Ergonomic Testing: Utilize the assert_matches crate for pattern assertions and pretty_assertions for colored diffs on failure.
  • GN Configuration: Add with_unit_tests = true to your rustc_binary or rustc_library templates to generate test targets.

10. Framework and Build Rules

  • Target Edition: Set edition = "2024" for new BUILD.gn Rust targets.
  • Deprecated Crates: Do not use the fuchsia_zircon crate. Use the standard zx bindings or relevant crates.
  • Handle Methods: Do not include zx::AsHandleRef to call methods on handles. It is no longer needed.
  • Lazy Initialization: Do not use the lazy_static! macro. Use std::sync::LazyLock from the standard library instead.

11. Reviewing Changes

Upon finishing authoring a change to Rust code, you MUST use this skill to review the change. Verify that:

  • [ ] All use statements are grouped at the top of the file.
  • [ ] No shorthand or abbreviated names are used for variables or structs.
  • [ ] No #[allow(unused)] or #[allow(dead_code)] attributes remain in the final code.
  • [ ] Comments are targeted at human maintainers, not the AI agent.
  • [ ] Constants are used instead of magic values.
  • [ ] spawn vs spawn_local is correctly chosen based on Send requirements.
  • [ ] fuchsia_sync::Mutex is preferred if a mutex is strictly necessary.
  • [ ] #[fuchsia::test] is used for tests.
  • [ ] unwrap() and expect() are avoided where possible.
  • [ ] Every unsafe block has a // SAFETY: comment that details exactly why it is sound and necessary.
  • [ ] Unsafe operations within unsafe functions are wrapped in an explicit unsafe block.
  • [ ] Public types implement Debug and getter methods avoid get_.
  • [ ] Checked math is used on external or untrusted input.

References to Upstream Rust API Guidelines