Rust Style Guide

I'm working at a company with a very large Rust codebase with thousands of endpoints. We use multiple repos and each service publishes its API as crates. A few years ago those were manually written and teams used exhaustive enums frequently in their API. It did not prevent runtime issues as older clients could receive responses with new variants from newer servers. It also made versioning painful because semver would dictate a major bump, but Rust's nominal typing means that types from different major versions get different identities, making it very inconvenient to integrate with these types (think shared helper functions, extension traits, ...). This caused people to release new variants in feature bumps and wreck havoc in the dependency tree by breaking compilation of intermediate libs.

Since then we switched to code generation from an IDL for the API model. I was leading this project and decided to produce non_exhaustive enums for the Rust code: it was 2 years ago and the situation drastically improved.

We have a CI step running lints with `non_exhaustive_omitted_patterns` mentionned in an other comment. That's the right approach for such a public API. The big difference is that is that warnings are local to the crate you're working on, so they're more actionable than errors.

This was all in the context of modeling the API of a distributed system. I still tend to use non_exhaustive more often now even for regular helper libraries. It always requires some thought as you need to plan for the forward compat of your code.

At Google, the bottleneck is that a team changing a commonly used enum will not know how to update all the broken use sites, since it can be affecting dozens or hundreds of teams.

It is better to decouple the enum change from the use site change and let consuming teams update on their own schedule.

Honestly what I tend to see is that most enums are not exposed publicly at all besides maybe error types and configuration options (where the user usually constructs but does not match on them). In both cases #[non_exhaustive] is valid. For all of the non-public enums you get to enjoy the compiler exhaustiveness enforcement.

It's always up to callers to decide to handle everything, or decide that additions are non-fatal and use a wildcard branch to ignore them. The same enum could need to be exhaustive for one use case, or subset matched by another.

It’s the eternal struggle between flexibility and strictness that doesn’t really have a silver bullet answer. Or maybe it’s better framed as “flexibility, safety, backwards compatibility, pick any two”?

I just fundamentally disagree with Google on how to evolve data structures. Sloppy open-domain protobuf field presence, enum values, whatever are illusory extension points. Better to have discrete versions of a data structure --- Foo1, Foo2, Foo3, etc., and rigid checking in each one than to have just one "Foo" with optional-everything that changes implicitly over time.

Given that a crate is the unit of build parallelization in Rust, there's a benefit to more crates especially when they don't cost much cognitive overhead. You could imagine using crates in the way you'd typically use separate mods in a normal Rust project.

I dug around in their code search to find some examples but didn't see much Rust in there, seems still early. I think https://source.chromium.org/chromium/chromium/src/+/main:tes... has ~4 Rust files that end up separate crates though. (One of them defines a proc macro so even in a Cargo built Rust project it would need to be in its own separate crate, I think!)

I guess smaller crates and avoiding nested modules could also help optimize for making the code greppable by coding agents without blowing up context windows.

I think one benefit of small crates is that it gives you more granularity in linking and dependency graphs, which is especially relevant for rebuilds. At a previous job we had a monolithic "utilities" crate, and this caused problems when you tried to depend on it for the IP address utilities but this brought in the radio frequency utilities. When one of these submodules got an update the versioning would excessively propagate downstream to every consumer. If this was organized as small "net-utils" and "rf-utils" crates then maybe it would not have been as much of an issue.

So a single crate has to be as small as possible so builds are fast & cachable.

OTOH if you have one crate with lots of modules, it's tempting to import anything anywhere and use pub(crate). Rustdoc needs to be configured to show private items if you want to see internal APIs.

As a solo programmer, I still prefer C and C++. In fact, as I've incorporated LLMs in to my workflow, I've been increasingly drawn toward C and its simplicity. A lot of the QoL features of C++ simply aren't needed when you're writing less code manually.

Even disregarding tooling I'm actually happier writing C than (even) Odin because it's really just a natural end state of changes I'd made to how I write code over the past 7-8 years and what I expect from a language (to not do much, and to not get in the way).

It's hard to compete with the tangibles of writing/using C:

- Somehow it has shorter compile times than everything else still, particularly for release builds?

- Everything that matters (to me) has C bindings.

- All the tools just work and they work well (and a lot of them are made specifically for C anyway).

- The compilation model is actually better, more straight forward and easier to make fast than languages that try to "fix" it, unless you sit there fighting it and overcomplicate it with overwrought build systems. (`make` is better than I used to give it credit for, though).

I think Ada is the only language that could peel my attention away from C at the moment, which is ironic given my "Don't do much, get out of my way" stance. It turns out you can do more if you're sensibly designed, have the right escape hatches and actually provide real, useful features (basically every feature regarding arrays in Ada and their interplay with other features like index types, etc.). Ada is not as easy to port from Odin, though, and Ada would be a much bigger gamble than C in so many ways. We don't mind writing the code we use ourselves (we in fact prefer it), but in Ada a lot of that code would be decidedly alien to how Ada seems to work in many ways.

With that said, I do have an Ada port of a game I was working on that does illustrate a lot of upsides. It's a different possible end state.

P.S. I've tried Zig, I wrote Zig for several years before I started using Odin, it's what got me back to imperative, small, native languages. It's what started this journey back to C.

Ah and Rust's compiler backend dependency on LLVM and in the future GCC as well.

Adding Rc/Arc is just another layer of indirection and noise that makes the code hard to read.

That being said I don't particularly understand your conception of a method. They are both methods. The getter ought to have a shorter name since it is probably called more frequently and because it inherently has less of an impact -- this goes along with the principle that names that demand attention should be larger and easier to notice.

https://protobuf.dev/reference/rust/rust-generated/

A builder type like `Command` will have unqualified setters and `get_` qualified getters.

For record-like-structs, I think unqualified getters becomes preferred and `set_` qualified setters.

> I guess you would code manually every now and then for your own enjoyment but at that point do you care about style guides written for scale?

I think they're still quite valuable in that case, for a couple reasons:

- When learning a new language (which happens much more frequently when writing code "for pleasure," as it were), "written for scale" guidelines still translate pretty well to "written for oneself" IME. At the very least, they tell you what to expect in code you read, and give you a reasonable starting point as you develop your own taste and stylistic preferences.

- I've noticed some open source projects beginning to institute anti-AI contribution guidelines, and such projects still benefit from codified style guides. Google obviously doesn't fall under this category themselves, but in other language ecosystems, their style guides tend to find use in OSS projects.

What have you produced with your agentic army? Would you like to share with the class?

It seems to me that if the intent is not just to produce code but also to operate it, having the different pieces behave in a similar, predictable way is kind of nice. Whether the software is written by AI or humans.

I would think they're probably even more meaningful in an agentic world.

Shitty generals can't review meaningfully review the work of their troops.

On top of that all, I just enjoy programming itself. It's less and less of the meat of a software job over time, but I was coding before I got paid for it, and I'll probably keep coding well after I can get paid for it.

I guess you would type out a comment manually every now and then for your own enjoyment, but at that point do you really care about comments at scale?

---

EDIT (above is a joke) It's very important that every time you find something that is of no use to you, you write a comment explaining that this link is of no interest to you, discouraging people from things you have no interest in. Monoculture for all!

Unless you're working on your own project on which you have full control, or you have a strong authority figure in your company who cares about that, it's a lost battle.

It's sad for anyone who love their craft, but tbh I'm not even sure it matters anymore for most projects.