2026 update by ralfbiedert · Pull Request #54 · microsoft/rust-guidelines

ralfbiedert · 2026-06-15T16:05:47Z

No description provided.

geeknoid · 2026-06-15T18:24:25Z

@@ -0,0 +1,22 @@
+<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->
+
+## Avoid meta design documentation (M-NO-META-DESIGN-DOCUMENTATION) { #M-NO-META-DESIGN-DOCUMENTATION }


I often tell the AI "Remove narrative-style comments" which tends to trim out the frequent play-by-play that the AI inserts inside of code blocks.

geeknoid · 2026-06-15T18:25:17Z

-## Design with AI use in Mind (M-DESIGN-FOR-AI) { #M-DESIGN-FOR-AI }
+## Design with AI use in mind (M-DESIGN-FOR-AI) { #M-DESIGN-FOR-AI }

 <why>To maximize the utility you get from letting agents work in your code base.</why>


Search and replace "code base" to "codebase" throughout.

geeknoid · 2026-06-15T18:25:59Z

+
+It is prudent to separate domain aspects from language aspects. Domain aspects address business problems. An algorithm to compute prime numbers or logic for processing a customer table can (and should) work the same when translating between languages. 
+
+However, many patterns exist to solve problems particular to the ecosystem they stem from. The Rust ecosystem has its own problems, and these need to be addressed by idioms that work for Rust. This includes


Suggested change

However, many patterns exist to solve problems particular to the ecosystem they stem from. The Rust ecosystem has its own problems, and these need to be addressed by idioms that work for Rust. This includes

However, many patterns exist to solve problems particular to the ecosystem they stem from. The Rust ecosystem has its own problems, and these need to be addressed by idioms that work for Rust. These include

geeknoid · 2026-06-15T18:27:55Z

 <!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->

-## Applications may use Anyhow or Derivatives (M-APP-ERROR) { #M-APP-ERROR }
+## Applications may use Anyhow or derivatives (M-APP-ERROR) { #M-APP-ERROR }


SHould update this guideline to factor in ohno

geeknoid · 2026-06-15T18:33:08Z

+
+Panic recovery via `catch_unwind()` is a matter of last resort and should generally be followed by a controlled application restart. 
+
+Panics indicate the program has reached an unrecoverable state (compare [M-PANIC-IS-STOP](../../universal/#M-PANIC-IS-STOP) and [M-PANIC-ON-BUG](../../universal/#M-PANIC-ON-BUG)). Library code in particular should not attempt to catch a panic and continue execution, as there is a risk of observing otherwise impossible state:


I think we should be stronger and more explicit about libraries. "Should not" shoudl be "must not", and I'd put the library text in its own paragraph

geeknoid · 2026-06-15T18:33:52Z

@@ -0,0 +1,20 @@
+<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->
+
+## Prefer 'macros by example' over proc macros (M-MBE-OVER-PROC) { #M-MBE-OVER-PROC }


"MBE" is pretty cryptic, I'd spell that out.

geeknoid · 2026-06-15T18:34:35Z

@@ -0,0 +1,31 @@
+<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->


Should we have a guideline to recommend CompactString?

geeknoid · 2026-06-15T18:35:51Z

+
+Frequently used, internal, immutable sequences that will not be resized after construction should be stored as `Box<[T]>`, `Arc<str>` or similar, rather than their original  `Vec<T>` or `String` counterparts.
+
+Regular growable collections consist of a `(ptr, len, capacity)` triple. Converting them to boxed slices makes them immutable and drops the `capacity` bit, reducing their handle size by 1/3.  For this pattern to be useful, the following preconditions should apply:


And more importantly, it also frees the extra space in the collection.

geeknoid · 2026-06-15T18:36:30Z

+- the sequence should be frequently instantiated (e.g., >1000's of instances),
+- it must be immutable,
+- it should not be user-visible, i.e., regular users would just deal with `&str` or similar,
+- the sequence payload should be relatively small.


Why this constraint?

geeknoid · 2026-06-15T18:37:34Z

@@ -0,0 +1,48 @@
+<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->
+
+## Reuse allocations where possible (M-MEM-REUSE) { #M-MEM-REUSE }


SHould we have a guidelines recommending the use of an arena ellocator for any growth-free allocation patterns?

geeknoid · 2026-06-15T18:38:45Z

@@ -0,0 +1,10 @@
+<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->
+
+## All crates are siblings in one folder (M-CRATES-FLAT-FOLDER) { #M-CRATES-FLAT-FOLDER }


I don't agree with this guideline. In the SuperScalar tree, we have a lot of crates, and I've created a deeper hierarchy to help categorize them and scope their usage.

geeknoid · 2026-06-15T18:39:45Z

@@ -0,0 +1,12 @@
+<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->
+
+## MSRV is conservatively updated (M-MSRV) { #M-MSRV }


I think we should take a strong position here. Something like:

"Ideally, MSRV tracks one year's worth of Rust compiler releases, which is usually 9 releases prior to the current stable release"

geeknoid · 2026-06-15T18:41:07Z

+
+Any repo with two or more crates that somehow belong together should unify these crates with a workspace `Cargo.toml`. Members then inherit shared metadata and dependency versions from the workspace root via `[workspace.dependencies]`, `[workspace.lints]`, ... rather than duplicating these values in each crate. 
+
+Where a dependency is crate-specific, it should still be defined in the workspace. Workspace definitions should generally not enable dependency features (except basic ones such as `["std"]`), and may even consider `default-features = false` for large projects.


I think instead, we should explicitly recomment using default-features=false in the root crate and let the lower-level crates add the features they specifically need. And I think we could have a tip recommending cargo-ensure-no-default-features to help with this.

ralfbiedert added 10 commits January 23, 2026 13:22

Add claude file with ground rules.

f9671a2

Update file.

1d0fc4a

Disable options for incompatible plugins and 0.5 changes.

ac034e4

Fix casing.

01c00c3

Disable confusing nav sections.

4e5d081

40+ more guidelines.

169c3f0

Cleanup.

497fcd6

Crosslink guidelines.

369fb00

Fix remaining TODOs.

9a15dfc

Integrate feedback.

b7af821

geeknoid reviewed Jun 15, 2026

View reviewed changes

		@@ -0,0 +1,22 @@
		<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->

		## Avoid meta design documentation (M-NO-META-DESIGN-DOCUMENTATION) { #M-NO-META-DESIGN-DOCUMENTATION }


		It is prudent to separate domain aspects from language aspects. Domain aspects address business problems. An algorithm to compute prime numbers or logic for processing a customer table can (and should) work the same when translating between languages.

		However, many patterns exist to solve problems particular to the ecosystem they stem from. The Rust ecosystem has its own problems, and these need to be addressed by idioms that work for Rust. This includes


		Panic recovery via `catch_unwind()` is a matter of last resort and should generally be followed by a controlled application restart.

		Panics indicate the program has reached an unrecoverable state (compare [M-PANIC-IS-STOP](../../universal/#M-PANIC-IS-STOP) and [M-PANIC-ON-BUG](../../universal/#M-PANIC-ON-BUG)). Library code in particular should not attempt to catch a panic and continue execution, as there is a risk of observing otherwise impossible state:

		@@ -0,0 +1,20 @@
		<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->

		## Prefer 'macros by example' over proc macros (M-MBE-OVER-PROC) { #M-MBE-OVER-PROC }

		@@ -0,0 +1,31 @@
		<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->


		Frequently used, internal, immutable sequences that will not be resized after construction should be stored as `Box<[T]>`, `Arc<str>` or similar, rather than their original `Vec<T>` or `String` counterparts.

		Regular growable collections consist of a `(ptr, len, capacity)` triple. Converting them to boxed slices makes them immutable and drops the `capacity` bit, reducing their handle size by 1/3. For this pattern to be useful, the following preconditions should apply:

		@@ -0,0 +1,48 @@
		<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->

		## Reuse allocations where possible (M-MEM-REUSE) { #M-MEM-REUSE }

		@@ -0,0 +1,10 @@
		<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->

		## All crates are siblings in one folder (M-CRATES-FLAT-FOLDER) { #M-CRATES-FLAT-FOLDER }

		@@ -0,0 +1,12 @@
		<!-- Copyright (c) Microsoft Corporation. Licensed under the MIT license. -->

		## MSRV is conservatively updated (M-MSRV) { #M-MSRV }


		Any repo with two or more crates that somehow belong together should unify these crates with a workspace `Cargo.toml`. Members then inherit shared metadata and dependency versions from the workspace root via `[workspace.dependencies]`, `[workspace.lints]`, ... rather than duplicating these values in each crate.

		Where a dependency is crate-specific, it should still be defined in the workspace. Workspace definitions should generally not enable dependency features (except basic ones such as `["std"]`), and may even consider `default-features = false` for large projects.

Conversation

ralfbiedert commented Jun 15, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants