Skip to content

morganlinton/BeautifulRust / skills/rust-best-practices

rust-best-practices

Unverified

Write idiomatic, robust, maintainable Rust. Use this skill whenever you write, review, refactor, debug, or explain Rust code: new crates, modules, functions, structs, traits, error types, async code, unsafe or FFI code, Cargo.toml, tests, or rustdoc. Trigger on any mention of Rust, cargo, crates, .rs files, the borrow checker, lifetimes, traits, clippy, or rustfmt, even when the user does not ask for "best practices" or "idiomatic" code. Synthesized from the Google Rust Style Guide, the Rust API Guidelines, Effective Rust, Rust Design Patterns, and Microsoft's Pragmatic Rust Guidelines.

FileKindSize
SKILL.mdskill md29.0 KB
evals/bevy-arena-regen/case.yamlconfig783 B
evals/bevy-arena-regen/files/Cargo.lockmanifest32.5 KB
evals/bevy-arena-regen/files/Cargo.tomlmanifest354 B
evals/bevy-arena-regen/files/src/lib.rsscript6.2 KB
evals/bevy-arena-regen/files/tests/arena.rsscript3.3 KB
evals/bevy-arena-regen/graders/01-builds-and-tests-pass.mdmarkdown167 B
evals/bevy-arena-regen/graders/02-regen-tested-headless.mdmarkdown272 B
evals/bevy-arena-regen/graders/03-system-params-by-value.mdmarkdown212 B
evals/bevy-arena-regen/graders/04-keeps-bevy-prelude.mdmarkdown159 B
evals/bevy-arena-regen/graders/05-plain-data-components.mdmarkdown208 B
evals/bevy-arena-regen/graders/06-ordered-after-damage.mdmarkdown334 B
evals/bevy-arena-regen/graders/07-no-panicking-queries.mdmarkdown186 B
evals/bevy-arena-regen/graders/08-clippy-clean.mdmarkdown125 B
evals/bevy-arena-regen/graders/09-health-never-exceeds-max.mdmarkdown134 B
evals/bevy-arena-regen/graders/10-existing-code-not-rewritten.mdmarkdown275 B
evals/bevy-arena-regen/place-files.shexecutablescript62 B
evals/bevy-arena-regen/prompt.mdmarkdown480 B
evals/log-summary-cli/case.yamlconfig581 B
evals/log-summary-cli/graders/01-never-panics-on-bad-input.mdmarkdown212 B
evals/log-summary-cli/graders/02-errors-name-the-file.mdmarkdown104 B
evals/log-summary-cli/graders/03-malformed-lines-counted.mdmarkdown186 B
evals/log-summary-cli/graders/04-paths-as-path-types.mdmarkdown168 B
evals/log-summary-cli/graders/05-sorted-and-skipped-count.mdmarkdown150 B
evals/log-summary-cli/graders/06-dependency-ranges.mdmarkdown134 B
evals/log-summary-cli/graders/07-map-based-counting.mdmarkdown103 B
evals/log-summary-cli/graders/08-aggregation-unit-tested.mdmarkdown147 B
evals/log-summary-cli/prompt.mdmarkdown730 B
evals/refactor-inventory-module/case.yamlconfig677 B
evals/refactor-inventory-module/files/inventory.rsscript3.2 KB
evals/refactor-inventory-module/graders/01-deny-warnings-removed.mdmarkdown90 B
evals/refactor-inventory-module/graders/02-no-rc-refcell-in-api.mdmarkdown141 B
evals/refactor-inventory-module/graders/03-borrowed-param-types.mdmarkdown157 B
evals/refactor-inventory-module/graders/04-error-implements-error.mdmarkdown108 B
evals/refactor-inventory-module/graders/05-no-unwrap-on-fallible-paths.mdmarkdown209 B
evals/refactor-inventory-module/graders/06-getter-renamed.mdmarkdown132 B
evals/refactor-inventory-module/graders/07-bool-param-replaced.mdmarkdown117 B
evals/refactor-inventory-module/graders/08-deterministic-report.mdmarkdown114 B
evals/refactor-inventory-module/graders/09-format-over-concat.mdmarkdown119 B
evals/refactor-inventory-module/graders/10-no-check-then-unwrap.mdmarkdown128 B
evals/refactor-inventory-module/graders/11-changes-listed-with-reasons.mdmarkdown94 B
evals/refactor-inventory-module/graders/12-signature-changes-called-out.mdmarkdown201 B
evals/refactor-inventory-module/place-files.shexecutablescript62 B
evals/refactor-inventory-module/prompt.mdmarkdown507 B
evals/semver-library-api/case.yamlconfig575 B
evals/semver-library-api/graders/01-implements-fromstr.mdmarkdown141 B
evals/semver-library-api/graders/02-implements-display.mdmarkdown94 B
evals/semver-library-api/graders/03-dedicated-error-type.mdmarkdown164 B
evals/semver-library-api/graders/04-common-traits-derived.mdmarkdown127 B
evals/semver-library-api/graders/05-fields-private.mdmarkdown125 B
evals/semver-library-api/graders/06-rustdoc-with-errors-section.mdmarkdown132 B
evals/semver-library-api/graders/07-doc-examples-use-question-mark.mdmarkdown86 B
evals/semver-library-api/graders/08-precedence-rules-tested.mdmarkdown152 B
evals/semver-library-api/graders/09-no-unwrap-in-library-code.mdmarkdown136 B
evals/semver-library-api/graders/10-eq-hash-agree-with-ord.mdmarkdown258 B
evals/semver-library-api/prompt.mdmarkdown667 B
references/bevy.mdmarkdown7.0 KB
references/effective-rust.mdmarkdown13.9 KB
references/google-rust-style-guide.mdmarkdown10.7 KB
references/microsoft-rust-guidelines.mdmarkdown16.2 KB
references/rust-api-guidelines.mdmarkdown11.2 KB
references/rust-design-patterns.mdmarkdown8.2 KB

references/google-rust-style-guide.md

View on GitHub
# Google Rust Style Guide (digest)

Source: https://google.github.io/styleguide/rustguide.html . Google's internal guide,
also adopted by Android, Chromium, and Fuchsia. It defers to the official Rust Style
Guide and API Guidelines and adds rules on top. API-design rules are binding for library
code and a strong recommendation for application code, which "should generally favor
simplicity and directness over broad reusability". Read this for formatting, imports,
module layout, accessor naming, and the application-vs-library distinction. Rules
specific to Chromium or Fuchsia builds are omitted below.

## Background and goals

Readability over writeability; automation (large-scale changes should be mechanical);
consistency with the Rust ecosystem; rules must pull their weight. Follow the official
Rust Style Guide and API Guidelines unless this guide conflicts. rustfmt enforces most
formatting automatically.

## Code organization

- Prefer small crates, ideally but not necessarily a single file. Larger crates are
  allowed for orphan-rule coherence or foundational libraries. Decide crate boundaries
  before submodules; the root may re-export from leaf submodules.
- Name a leaf module after its primary item: `Foo` gives `mod foo` / `foo.rs`.
- Non-leaf modules contain only `mod` declarations and re-exports. Small "ties things
  together" code is tolerated. Leaf modules may include `mod tests`.
- No glob imports, except at reviewer discretion: `use super::*` in inline modules,
  `use Enum::*` in enum method bodies, `pub use submodule::*` in non-leaf modules.
  Avoid defining preludes.
- One module per `use` statement (rustfmt `imports_granularity = Module`): no `::`
  inside braces.

  ```rust
  use foo::bar::{Bar, Baz};  // OK
  use foo::{Foo, bar::Bar};  // avoid
  ```

- Import traits inside function bodies unless the trait is used throughout the file.
- Qualify free function calls by module (`mem::transmute(y)`, not `transmute(y)`), but
  use types and traits unqualified (`Regex`, not `regex::Regex`). Exceptions: ambiguous
  names such as `io::Error` (or `use std::io::Error as IoError`), large type groups,
  macros and generated code.

## Formatting

- Always run the formatter. Recommended rustfmt settings: `max_width = 100`,
  `hex_literal_case = Lower`, `format_macro_matchers = true`.
- `#[rustfmt::skip]` only for deliberate manual alignment or generated code, never for
  personal style.

## Ownership and borrowing

- Avoid `Rc` / `Arc`; prefer unique ownership. Exception: when the alternative is
  unreasonably complex, a review judgment call.
- Borrow rather than `.clone()`. Clone when a real deep copy is needed or borrowing
  becomes excessively complex, and weigh performance. Cloning `Rc` / `Arc` is expected.

## Function inputs and outputs

- Accept the most flexible borrowed type: `&[T]` not `&Vec<T>`, `&str` not `&String`,
  `&T` not `&Box<T>`, `Option<&T>` not `&Option<T>` (clippy `borrowed_box`, `ptr_arg`).
- Library code returns iterators (concrete or `impl Iterator`) instead of `Vec<T>` and
  accepts `impl IntoIterator` when only iterating. Application code may return or take
  `Vec` / `&[T]` when simpler. Exceptions: callers need an owned vector, random
  indexing, or the function's purpose is building a collection.
- `impl Into<T>` parameters only where call-site ergonomics are paramount, weighed
  against code bloat. Application code should almost never use them.
- Use an `enum` instead of a `bool` parameter when the purpose isn't obvious. If you
  keep a `bool`, add an inline comment at the call site.
- Errors, chosen by API contract: `Option` for obvious failures (`checked_add`);
  `Result` when the caller needs details (`fn open_file(path: &Path) -> Result<File,
  io::Error>`); `panic!` for bugs and violated invariants, which must be fixed in the
  code, not handled at runtime. Developer-facing binaries may panic on non-fatal
  errors; tests may panic for assertions.

## Types

- Use a newtype rather than an alias for notable semantic differences, a type needing
  its own API, a possible future change of underlying type, or type safety
  (`Day` / `Month` / `Year`).
- Prefer named fields over tuples, since `.0` and `.1` get confusing. Exceptions:
  single-field newtypes and very local contexts.

## Traits

- Add trait impls when needed. Low-level library code anticipates needs; application
  code adds them on demand.
- Implement the std trait instead of a custom method: `impl FromStr for Foo`, not
  `fn from_str` (clippy `should_implement_trait`). Keeping both is acceptable.
- Use `#[derive]` wherever it can express the impl.
- Library code accepts generics (`T: Trait`, `impl Trait`) over `dyn Trait`, except when
  code size matters. Reasons: vtable indirection, no inlining, and some traits are not
  dyn-compatible (generic functions, associated functions without `self`, functions
  returning `Self`).
- Define a trait only for generic programming, for accepting or returning
  `impl` / `dyn Trait`, or as an extension trait. Otherwise use an inherent impl.
  Don't use traits merely to organize code.
- Extension traits: suffix `Ext`, sole purpose is adding methods (not for generics or
  `dyn`), owned by the team that owns the extended type.
- Trait guidance: types with public fields implement traits all subfields implement.
  Error types: `Copy` when possible. `Copy` whenever it will clearly stay `Copy`;
  `Clone` for most types except external resources; `Default` when there is a `new()` or
  default state (clippy `new_without_default`); `PartialEq` over `Eq` unless you need
  reflexivity; `PartialOrd` over `Ord` unless you need a total order; map keys get
  `Hash` and `Eq`, plus `Ord` if there is a clear total order.
- Pair an important `From` impl with an inherent `::new()`, `::new_from_foo()`, or
  `::from_foo()`.
- Bag-of-options structs with all-public fields implement `Default`, enabling
  `..Default::default()`.

## Concurrency

- Never reach inside a poisoned mutex, "no matter how tempting".
- Library code should not start threads itself.

## Macros

Preference order: plain functions, types, traits, and modules; then `macro_rules!`;
then other codegen; then `proc_macro`. Weigh IDE and code-search costs, dialect
creation, and difficulty of large-scale changes.

## Naming

- Methods follow std style: `as_`, `to_`, `into_` with the matching `self` convention
  (clippy `wrong_self_convention`).
- Lifetimes should be descriptive, especially on types. Exceptions: generic abstractions
  like `Cow`, `'_`, and single-character names for simple input/output relationships.
- Generic parameters: short, related to what they represent, ideally the letter from the
  most important bound. `T` / `U` for APIs meant for almost any type.
- Constructors: `new()` or `new_with_foo()`; `try_new()` if fallible. Value-to-value
  conversions: `from_foo()` with a `From` impl.
- Avoid abbreviations outsiders won't know, including acronyms and letter-dropping.
  Exceptions: Wikipedia-common terms and clear cases like `IpAddr`.

## Documentation

- Document public APIs; consider the `missing_docs` lint.
- Include examples somewhere in the crate, not necessarily on every function.
- Document panics caused by malformed input, and invariants of unsafe functions and
  traits.
- Use capitalization and punctuation. Don't explain language basics. Comments must add
  information: `/// Removes an element.` on `remove_element()` is bad; omit it or allow
  the lint. Enum variant docs are often omittable.
- `///` for items; `//!` at the top of a file for modules and crates; Markdown; `//` for
  implementation notes, TODOs, and commented-out code. Mixing `///` and `//` on one item
  is fine:

  ```rust
  /// Finds the first `FooItem` with the given `name`, or `None` if not present.
  // TODO(issue-12345): `name` should be &str, not String.
  ```

- Prefer plain doc comments over macro-generated docs.

## Other Rust features

- **Unsafe**: don't write it unless safe code cannot do the same. Wrap it in a safe
  abstraction, isolate it (ideally in its own crate with few dependencies), add a
  `SAFETY:` comment, and justify it, with benchmarks if performance is the reason.
- **Unstable features**: don't use them.
- **Accessors**: `foo()` returns the value or a reference, `foo_mut()`, `take_foo()`,
  `set_foo(T)`, `replace_foo(T) -> T`, and `with_foo(|f| ..)` / `with_mut_foo(|f| ..)`
  for closure access. Closure accessors suit interior-mutability wrappers (`Mutex`,
  `RefCell`) or follow-up validation where `set_foo` can't be used.
- If you implement `len()`, also implement `is_empty()` (clippy `len_without_is_empty`).
- Don't access `#[doc(hidden)]` items you don't own.
- Mark a public function `const` only if it will stay `const`; removing `const` is
  breaking.
- Overload operators only for their mathematical or logical meaning, not as sugar.
- `#[non_exhaustive]` on public enums and public-field structs used across teams.
  Exceptions: stable ontologies (`Color`), two-state enums, or a commitment to fixing
  breakage with a large-scale change (clippy `exhaustive_enums`).
- `#[must_use]` on functions when ignoring the return is a misuse (pure functions like
  `HashMap::get()`) or the return carries errors or critical info; not needed if the
  return type already has it (`Result`). On types returned by such functions: error
  types and lazy computations.
- Run no code before `main()` (no `ctor` crate).

## Implementation concerns

- Don't overuse inference. Add explicit types for `.into()`, `.parse()`, and complex
  iterator results. Prefer typed variable declarations to turbofish; use `_` where the
  compiler forces a turbofish.
- Pattern-match instead of check-then-unwrap: `if let Some(value) = option { .. }`, not
  `is_some()` followed by `unwrap()`.
- Use `expect("reason")` over `unwrap()` when a panic is unavoidable.
- On `#[non_exhaustive]` enums, list every variant you handle, with a wildcard for the
  rest. Use `if let` or `let .. else` when you care about one variant
  (lint `non_exhaustive_omitted_patterns`).
- Add context strings to `assert!`, especially when a human will see the failure or to
  distinguish API misuse from bugs:

  ```rust
  assert!(self.stream.is_some(), "Call connect() before executing queries");
  ```

  Don't repeat the condition as the message.
- Avoid long or complex iterator chains. Don't put a chain in a `for` header; bind it to
  a variable first. Avoid `for_each`. Short chains are fine:
  `values.iter().any(|&v| v > threshold)`.
- Don't call `panic::catch_unwind` in first-party code, except as defense in depth that
  is never relied on, and only where `panic = "unwind"` applies.
- Use `format!` / `write!` to concatenate more than two strings (`format!("{a}{b}{c}")`)
  and for substitutions instead of `str::replace`.

## Tests

Use the codebase's test framework. Tests may use panics for assertions. Tests live in a
`mod tests` inside leaf modules.
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall