0xmassi/google-rust-style-skill/google-rust-style

Google Rust style

Source: Google Rust Style Guide, read 2026-10-22 at gh-pages 2ac1584. Section links below use G#anchor, short for https://google.github.io/styleguide/rustguide.html#anchor.

This skill holds only what Google adds on top of common Rust advice (borrow before you clone, thiserror for library errors, cargo clippy clean). Pair it with a general Rust skill for the basics. Where common advice disagrees with Google, Google wins (see Overrides).

Out of scope: rules tagged Chrome, Fuchsia or Android (small crates, flat rust_library layout, chromium::import!, no async, no std::thread, fuchsia_sync::Mutex, per-codebase test frameworks).

Library or application

First decide which kind of crate you are in (G#api-design-context):

• Library: used by other projects and solves a general problem. Every API rule here binds.
• Application: one app and one specific problem. API rules are strong recommendations, and simplicity and directness win over reuse.

Rules below marked library follow this split. Every other rule binds both kinds: an application with no outside users still takes the full rustfmt and clippy config except the library block, and every layout, import, error, naming and unsafe rule.

1. Tool config

Run cargo clippy --all-targets --all-features -- -D warnings in CI so every warn below fails the build.

rustfmt.toml. All three options need nightly rustfmt. Stable 1.98 prints "unstable features are only available in nightly" and ignores them, and the guide lets a stable-only codebase skip them. max_width = 100 is already rustfmt's default, so it is not set.

imports_granularity = "Module"
hex_literal_case = "Lower"
format_macro_matchers = true

clippy.toml. avoid-breaking-exported-api = false is load-bearing. Without it, wrong_self_convention and ref_option skip pub items, which are exactly the items Google's rules target.

avoid-breaking-exported-api = false
allow-unwrap-in-tests = true
disallowed-methods = [
  { path = "std::panic::catch_unwind", reason = "Google Rust style forbids catch_unwind in first-party code" },
  { path = "std::sync::PoisonError::into_inner", reason = "Google Rust style: never reach inside a poisoned mutex" },
  { path = "std::sync::PoisonError::get_ref", reason = "Google Rust style: never reach inside a poisoned mutex" },
  { path = "std::sync::PoisonError::get_mut", reason = "Google Rust style: never reach inside a poisoned mutex" },
]

Cargo.toml, every crate. Drop unsafe_code = "forbid" only in the one crate that isolates unsafe code.

[lints.rust]
unsafe_code = "forbid"
unstable_features = "deny"
 
[lints.clippy]
ref_option = "deny"
unwrap_used = "deny"
wildcard_imports = "deny"
needless_for_each = "deny"
undocumented_unsafe_blocks = "deny"
derive_partial_eq_without_eq = "allow"
missing_const_for_fn = "allow"

Library crates merge these keys into the same two tables.

[lints.rust]
missing_docs = "warn"
 
[lints.clippy]
exhaustive_enums = "deny"
exhaustive_structs = "deny"
must_use_candidate = "deny"
return_self_not_must_use = "deny"
missing_panics_doc = "deny"

To take a guide-sanctioned exception, write #[expect(<lint>, reason = "...")] on the item. The reason carries the why, so the item needs no comment.

2. Judgement rules

No tool can check these. non_exhaustive_omitted_patterns is the lint the guide names for the matching rule, but it is unknown on stable 1.98 and needs a nightly feature, which would break the no-unstable-features rule. That rule stays here as prose.

Modules and imports

• A leaf module with one primary item Foo is mod foo in foo.rs. G#userdefined-item
• Non-leaf modules hold only mod declarations and re-exports, plus at most a little glue code. A mod tests or #[cxx::bridge] child still counts as a leaf module. G#non-leaf-modules
• Define no preludes. Using a third-party prelude is the reviewer's call. G#glob-imports
• Import a trait inside the function body that uses it, unless the whole file uses it. G#prefer-local-trait-imports
• Call free functions through their module: use std::mem; then mem::swap(..). Calling a name directly is fine when the name is already unambiguous (C++ interop) or the module name collides. G#toplevel-functions
• Name types unqualified: use regex::Regex; then Regex. Use the module path (io::Error) or a rename (IoError) for an ambiguous name, a large type family (rustc's hir), macros and generated code, and huge import lists. G#type-names

Formatting

• #[rustfmt::skip] is for hand alignment (matrices, rows of similar lines) and generated code only. Personal taste is not a reason. G#formatting-optout
• Write invisible characters in literals as escapes, such as \u{200D}. Clippy 0.1.98 does not flag a raw zero-width joiner. G#formatting-other

Ownership and signatures

• Model ownership as unique owners plus borrows. Reach for Rc/Arc only when that structure becomes unreasonably complex, and make the case in review. G#avoid-rc-arc
• Library: return an iterator (impl Iterator or a concrete type) instead of a Vec<T>. Return the Vec when most callers need one, the implementation naturally builds one, the result will be indexed, the function exists to build a collection, or it hands back an existing vector. Application: a Vec is fine. G#return-iterators
• Library: take impl IntoIterator when the function only iterates. Application: &[T] is fine. G#accept-iterators
• impl Into<T> parameters belong in library APIs where call-site ergonomics are paramount. Application code takes T. G#accepting-into
• When a bool argument's meaning is unclear at the call site, make it a two-variant enum. If you keep the bool, name it in an inline comment at the call site: connect(addr, /* retry= */ true). G#enum-vs-bool
• Choose the error contract:
• Option when the cause is obvious (checked_add, a missing value).
• Result when the caller needs the cause to recover (I/O, network).
• panic! for bugs and broken preconditions, which get fixed in code rather than handled at runtime.

Developer-facing binaries and tests may panic. A codebase may choose Result even for broken invariants. G#reporting-errors