blob: b58f4fddbe26c374d2d6dd70668ce2d0bfb00d7f [file] [view]
---
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:**
```rust
// 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:**
```rust
// 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:**
```rust
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
[C-CASE]: https://rust-lang.github.io/api-guidelines/naming.html#c-case
[C-CONV]: https://rust-lang.github.io/api-guidelines/naming.html#c-conv
[C-GETTER]: https://rust-lang.github.io/api-guidelines/naming.html#c-getter
[C-ITER]: https://rust-lang.github.io/api-guidelines/naming.html#c-iter
[C-ITER-TY]: https://rust-lang.github.io/api-guidelines/naming.html#c-iter-ty
[C-WORD-ORDER]:
https://rust-lang.github.io/api-guidelines/naming.html#c-word-order
[C-COMMON-TRAITS]:
https://rust-lang.github.io/api-guidelines/interoperability.html#c-common-traits
[C-CONV-TRAITS]:
https://rust-lang.github.io/api-guidelines/interoperability.html#c-conv-traits
[C-COLLECT]:
https://rust-lang.github.io/api-guidelines/interoperability.html#c-collect
[C-SERDE]:
https://rust-lang.github.io/api-guidelines/interoperability.html#c-serde
[C-SEND-SYNC]:
https://rust-lang.github.io/api-guidelines/interoperability.html#c-send-sync
[C-GOOD-ERR]:
https://rust-lang.github.io/api-guidelines/interoperability.html#c-good-err
[C-NUM-FMT]:
https://rust-lang.github.io/api-guidelines/interoperability.html#c-num-fmt
[C-RW-VALUE]:
https://rust-lang.github.io/api-guidelines/interoperability.html#c-rw-value
[C-SMART-PTR]:
https://rust-lang.github.io/api-guidelines/predictability.html#c-smart-ptr
[C-CONV-SPECIFIC]:
https://rust-lang.github.io/api-guidelines/predictability.html#c-conv-specific
[C-METHOD]:
https://rust-lang.github.io/api-guidelines/predictability.html#c-method
[C-NO-OUT]:
https://rust-lang.github.io/api-guidelines/predictability.html#c-no-out
[C-OVERLOAD]:
https://rust-lang.github.io/api-guidelines/predictability.html#c-overload
[C-DEREF]:
https://rust-lang.github.io/api-guidelines/predictability.html#c-deref
[C-CTOR]:
https://rust-lang.github.io/api-guidelines/predictability.html#c-ctor
[C-INTERMEDIATE]:
https://rust-lang.github.io/api-guidelines/flexibility.html#c-intermediate
[C-CALLER-CONTROL]:
https://rust-lang.github.io/api-guidelines/flexibility.html#c-caller-control
[C-GENERIC]:
https://rust-lang.github.io/api-guidelines/flexibility.html#c-generic
[C-OBJECT]: https://rust-lang.github.io/api-guidelines/flexibility.html#c-object
[C-NEWTYPE]:
https://rust-lang.github.io/api-guidelines/type-safety.html#c-newtype
[C-CUSTOM-TYPE]:
https://rust-lang.github.io/api-guidelines/type-safety.html#c-custom-type
[C-BITFLAG]:
https://rust-lang.github.io/api-guidelines/type-safety.html#c-bitflag
[C-BUILDER]:
https://rust-lang.github.io/api-guidelines/type-safety.html#c-builder
[C-VALIDATE]:
https://rust-lang.github.io/api-guidelines/dependability.html#c-validate
[C-DTOR-FAIL]:
https://rust-lang.github.io/api-guidelines/dependability.html#c-dtor-fail
[C-DTOR-BLOCK]:
https://rust-lang.github.io/api-guidelines/dependability.html#c-dtor-block
[C-DEBUG]: https://rust-lang.github.io/api-guidelines/debuggability.html#c-debug
[C-DEBUG-NONEMPTY]:
https://rust-lang.github.io/api-guidelines/debuggability.html#c-debug-nonempty
[C-SEALED]:
https://rust-lang.github.io/api-guidelines/future-proofing.html#c-sealed
[C-STRUCT-PRIVATE]:
https://rust-lang.github.io/api-guidelines/future-proofing.html#c-struct-private
[C-NEWTYPE-HIDE]:
https://rust-lang.github.io/api-guidelines/future-proofing.html#c-newtype-hide
[C-STRUCT-BOUNDS]:
https://rust-lang.github.io/api-guidelines/future-proofing.html#c-struct-bounds
[C-EVOCATIVE]:
https://rust-lang.github.io/api-guidelines/macros.html#c-evocative
[C-MACRO-ATTR]:
https://rust-lang.github.io/api-guidelines/macros.html#c-macro-attr
[C-ANYWHERE]: https://rust-lang.github.io/api-guidelines/macros.html#c-anywhere
[C-MACRO-VIS]:
https://rust-lang.github.io/api-guidelines/macros.html#c-macro-vis
[C-MACRO-TY]:
https://rust-lang.github.io/api-guidelines/macros.html#c-macro-ty
[C-CRATE-DOC]:
https://rust-lang.github.io/api-guidelines/documentation.html#c-crate-doc
[C-EXAMPLE]:
https://rust-lang.github.io/api-guidelines/documentation.html#c-example
[C-QUESTION-MARK]:
https://rust-lang.github.io/api-guidelines/documentation.html#c-question-mark
[C-FAILURE]:
https://rust-lang.github.io/api-guidelines/documentation.html#c-failure
[C-LINK]: https://rust-lang.github.io/api-guidelines/documentation.html#c-link
[C-HIDDEN]:
https://rust-lang.github.io/api-guidelines/documentation.html#c-hidden