r/rust • • Oct 21 '26

🧠 educational Google published its internal Rust style guide

/r/learnrust/comments/1xc2bmo/google_published_its_internal_rust_style_guide/
136 Upvotes

22 comments sorted by

63

u/teerre Oct 21 '26

I simultaneously like and dislike the first point. I can see how that helps with compile times and keeping crates small, but at the same time I can easily see this going sideways by having dozens of free files

40

u/Sad_Tap_9191 Oct 22 '26

Bazel/Ninja calls rustc without cargo, and there is no incremental build. If you edit a single file in a crate with 100 files, all files are compiled again.

I tried to connect a Rust library to packages in other languages with Bazel but gave up because of this.

9

u/protestor Oct 22 '26

there is no incremental build.

Why not????????

21

u/elprophet Oct 22 '26

Their blaze/bazel tooling likely makes this substantially less onerous than it seems

14

u/valarauca14 Oct 22 '26 edited Oct 22 '26

I don't believe it can. Granted it has been over a year since I had to put an :s/X/G/g on Googler but AFAIK rust incremental compilation breaks bazel deterministic (hermeticity & reproducibility) compilation. As the incremental (AFAIK) is based on the old build state, not purely the .rs files.

13

u/elprophet Oct 22 '26

Correct. Bazel pushes for small crates precisely because rules_rust and friends don't play with Cargo incremental compilation. The part the Gazelle tooling should help with is managing the Build and Cargo files that are necessary for Bazel's small crates determinism.

4

u/Illustrious_Car344 Oct 21 '26

I prefer smaller files (practically grew up with C# so I'm a little influenced), so I actually employ a conservitive use of subdirectories for repetitive things. Right now I have a folder full of callbacks for the scripting engine I'm embedding in my project, each file being callbacks for a different suite of functions, basically 1:1 with each library/service I'm exposing to the script engine.

In general I do agree with the flat file layout and I do try to adhere to that, but if it seems like an obvious fit, I use it without a second thought.

4

u/saint_marco Oct 22 '26

It's very common for big rust projects to be arranged as a cargo workspace with a forest of crates, this is farther in that direction.

3

u/iBPsThrowingObject Oct 22 '26

If you read the actual style guide instead of this LLM summary, that rule is explicitly about compile times. In fact, there is also a recommendation to keep crates as close to a single file as possible

12

u/dnew Oct 21 '26

Google's refactoring automations and SCM are amazing and awesome. I can fully see why you'd want to ensure making them possible to use. Nothing else is allowed (in general) to use globs either (like, BLAZE/BAZEL files have to list source files manually) for similar reasons.

25

u/Crinfarr Oct 22 '26

This all seems very specific to chrome/chromium other than "avoid arc/rc whenever possible"

6

u/Crinfarr Oct 22 '26

Also come to think of it "never use arc always use borrows" is probably also the result of chromium's existing c/++ architecture... Seems like it would lead to a bunch of dedicated owner classes that only exist to keep data (which does exactly the same thing as an arc but less efficient)

3

u/saint_marco Oct 22 '26

It's kind of ironic to have a style guide with a litany of special cases.

22

u/throwaway1847384728 Oct 22 '26

The name trips people up, but Google style guides aren’t about code formatting or intended to be general advice.

Their language style guides are specifically about providing considerations for how to use, or not use, language features within their code base.

That last part of key. It’s not generic “How to use Rust” advice.

It’s “How we decided it’s best for our employees to use Rust in the Google codebase”.

So rules that seem silly or wrong might have been added because it interacts with some other tooling or convention within the company.

2

u/0xMassii Oct 22 '26

Only six sections carry a [chrome] or [Fuchsia] tag: small crates, flat file layout, the import mechanism, no async/.await, no std threads, and fuchsia_sync::Mutex. The Rc/Arc rule and everything else is untagged.

Some of the untagged ones work in any codebase: no glob imports, expect over unwrap when an invariant can't go in the type system, foo() / foo_mut() / set_foo() / take_foo() for accessors, #[non_exhaustive] on public enums. The library vs application split near the top matters as well, since the API rules only bind for libraries.

I made an agent skill from the general parts and left the Chromium/Fuchsia/Android-only rules out, if you want to see what's left: https://github.com/0xMassi/google-rust-style-skill (not a Google project).

6

u/ak6te Oct 22 '26

The first bullet is unhinged.

0

u/sennalen Oct 22 '26

I don't find any of that surprising

-1

u/0xMassii Oct 22 '26

The section I'd read first is "Apply API design rules in context". API rules bind for library code and are only a strong recommendation for application code, with an explicit warning against premature generalization. Rules like avoiding dyn in library APIs or putting #[non_exhaustive] on public enums read differently once you know that.

A lot of the rest maps straight onto config. "A use statement should import items from one module" is imports_granularity = "Module" in rustfmt, which goes against the usual "Crate" advice. It needs nightly rustfmt. Stable prints a warning and skips it, and the guide allows a stable-only codebase to do the same.

On panics Google doesn't ban them. Use pattern matching over check-then-unwrap, and when an invariant can't live in the type system, write expect("why this holds") over unwrap. clippy's unwrap_used covers that and leaves expect alone.

Disclosure: I made an agent skill that turns the checkable rules into rustfmt.toml, clippy.toml and Cargo.toml [lints] tables, each setting mapped to the section it enforces: https://github.com/0xMassi/google-rust-style-skill (not affiliated with Google). A run on a 63k-line, seven-crate workspace turned up one trap you'll hit with or without the skill: unsafe_code = "forbid" breaks edition 2024 tests that call std::env::set_var, since that's unsafe now. deny plus #[expect(unsafe_code, reason = "...")] on those tests works.

-7

u/gbrennon Oct 22 '26

im curious to see ppl opinions about this style guide ;)

-8

u/hedgehog1024 Oct 22 '26

never use catch_unwind.

It is outright wrong when you code something like tokio or hyper. Granted, these aren't the usual things to make, but still.

6

u/0xMassii Oct 22 '26

The rule has an exception that covers part of your case. catch_unwind is allowed as defense in depth around critical entry points, as long as nothing relies on it and the author convinces the reviewer the code already does what it can to avoid panics. That exception only applies where panic=unwind is possible. Chrome, Android and Fuchsia all require panic=abort, so for them catch_unwind wouldn't catch anything. The text also scopes the ban to first-party code, which puts a runtime like tokio outside what it's talking about.

I made a skill that maps the checkable parts of the guide to rustfmt and clippy settings, if you want the rest as config: https://github.com/0xMassi/google-rust-style-skill (not affiliated with Google).