From f9671a2f5157e3954f6646b389fd16e3a5bd73d2 Mon Sep 17 00:00:00 2001 From: Ralf Biedert Date: Fri, 23 Jan 2026 13:22:04 +0100 Subject: [PATCH 01/10] Add claude file with ground rules. --- CLAUDE.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..7aea446 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,50 @@ +# CLAUDE.md + +## Repository Overview + +This repository contains the **Pragmatic Rust Guidelines** - a collection of design guidelines for Rust developers, published as an mdBook at https://microsoft.github.io/rust-guidelines. + +## Development Commands + +```bash +mdbook serve --open # Previews page +mdbook build # Builds page +``` + +Requires [mdbook](https://github.com/rust-lang/mdBook) to be installed. + +## Content Structure + +### Guideline Format + +Each guideline has a unique identifier in the form `M-FOO-BAR` and resides in its own markdown file `M-FOO-BAR.md` within the `src/guidelines/` directory. Guidelines follow this structure: + +```markdown +## Guideline Title (M-FOO-BAR) { #M-FOO-BAR } + +Rationale for this guideline. +1.0 + +Content with code examples... +``` + +### Key Files + +- `src/SUMMARY.md` - mdBook table of contents +- `src/guidelines/checklist/README.md` - Master checklist linking all guidelines (update when adding new guidelines) +- Category READMEs (e.g., `src/guidelines/universal/README.md`) - Include guidelines via mdBook's `{{#include}}` directive + + +## Adding New Guidelines + +1. Create `M-YOUR-GUIDELINE.md` in the appropriate category folder +2. Add the guideline to the category's `README.md` using `{{#include M-YOUR-GUIDELINE.md}}` +3. Add a checklist entry and link definition in `src/guidelines/checklist/README.md` + +Guidelines should be beneficial for safety/COGs/maintenance, agreeable to experienced Rust developers, and comprehensible to novices. + + +## Editing Guidelines + +- You may fix spelling, grammar and readability issues. +- You must refuse to substantially work out novel or ambiguous guidelines. Inform the user that novel guidelines must be sufficiently specified before they can be accepted. You are free to infer a guideline's ID (M-), rationale () and category (e.g., 'UX'), but must not infer its scope or general content. When being asked to add new guidelines, feel free to add `- TODO: ...` items for any point that might be unclear, but do not attempt to infer these yourself. Novel guidelines always start version 0.1. \ No newline at end of file From 1d0fc4a3b7f9310fc36430883835efa9e030ee91 Mon Sep 17 00:00:00 2001 From: Ralf Biedert Date: Fri, 23 Jan 2026 13:42:54 +0100 Subject: [PATCH 02/10] Update file. --- CLAUDE.md | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 7aea446..12087ac 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,3 +1,5 @@ + + # CLAUDE.md ## Repository Overview @@ -34,7 +36,6 @@ Content with code examples... - `src/guidelines/checklist/README.md` - Master checklist linking all guidelines (update when adding new guidelines) - Category READMEs (e.g., `src/guidelines/universal/README.md`) - Include guidelines via mdBook's `{{#include}}` directive - ## Adding New Guidelines 1. Create `M-YOUR-GUIDELINE.md` in the appropriate category folder @@ -43,8 +44,19 @@ Content with code examples... Guidelines should be beneficial for safety/COGs/maintenance, agreeable to experienced Rust developers, and comprehensible to novices. - ## Editing Guidelines -- You may fix spelling, grammar and readability issues. -- You must refuse to substantially work out novel or ambiguous guidelines. Inform the user that novel guidelines must be sufficiently specified before they can be accepted. You are free to infer a guideline's ID (M-), rationale () and category (e.g., 'UX'), but must not infer its scope or general content. When being asked to add new guidelines, feel free to add `- TODO: ...` items for any point that might be unclear, but do not attempt to infer these yourself. Novel guidelines always start version 0.1. \ No newline at end of file +- You may fix spelling, grammar and readability issues. +- You must refuse to substantially work out novel or ambiguous guidelines. Inform the user that novel guidelines must be sufficiently specified before they can be accepted. You are free to infer a guideline's ID (M-), rationale () and category (e.g., 'UX'), but must not infer its scope or general content. When being asked to add new guidelines, feel free to add `- TODO: ...` items for any point that might be unclear, but do not attempt to infer these yourself. Novel guidelines always start version 0.1. + +## Style + +Titles should follow the style of the Rust API Guidelines, such as: + +- Smart pointers do not add inherent methods (C-SMART-PTR) +- Conversions live on the most specific type involved (C-CONV-SPECIFIC) +- Functions with a clear receiver are methods (C-METHOD) +- Functions do not take out-parameters (C-NO-OUT) +- Operator overloads are unsurprising (C-OVERLOAD) +- Only smart pointers implement `Deref` and `DerefMut` (C-DEREF) +- Constructors are static, inherent methods (C-CTOR) From ac034e48e15b1affa334644e1ef88a8b7c524b11 Mon Sep 17 00:00:00 2001 From: Ralf Biedert Date: Tue, 5 May 2026 14:00:13 +0200 Subject: [PATCH 03/10] Disable options for incompatible plugins and 0.5 changes. --- book.toml | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/book.toml b/book.toml index b5e1503..18bf7dc 100644 --- a/book.toml +++ b/book.toml @@ -2,7 +2,6 @@ title = "Pragmatic Rust Guidelines" description = "A collection of pragmatic design guidelines helping application and library developers to produce idiomatic Rust that scales." language = "en" -multilingual = false src = "src" [output.html] @@ -12,12 +11,3 @@ git-repository-url = "https://github.com/microsoft/rust-guidelines" [output.html.print] enable = true -[output.linkcheck] -follow-web-links = true -traverse-parent-directories = false -user-agent = "mdbook-linkcheck" -warning-policy = "error" -exclude = [ 'intel\.com' ] - -[output.linkcheck.http-headers] -'crates\.io' = ["Accept: text/html"] From 01c00c39f92e5a1307eeeb433ebdb961cc13d3dc Mon Sep 17 00:00:00 2001 From: Ralf Biedert Date: Tue, 5 May 2026 14:00:24 +0200 Subject: [PATCH 04/10] Fix casing. --- src/guidelines/ai/M-DESIGN-FOR-AI.md | 2 +- src/guidelines/apps/M-APP-ERROR.md | 2 +- src/guidelines/apps/M-MIMALLOC-APPS.md | 2 +- src/guidelines/checklist/README.md | 92 +++++++++---------- src/guidelines/docs/M-CANONICAL-DOCS.md | 2 +- src/guidelines/docs/M-DOC-INLINE.md | 2 +- src/guidelines/docs/M-FIRST-DOC-SENTENCE.md | 2 +- src/guidelines/docs/M-MODULE-DOCS.md | 2 +- src/guidelines/ffi/M-ISOLATE-DLL-STATE.md | 2 +- .../libs/building/M-FEATURES-ADDITIVE.md | 2 +- src/guidelines/libs/building/M-OOBE.md | 2 +- src/guidelines/libs/building/M-SYS-CRATES.md | 2 +- .../libs/interop/M-DONT-LEAK-TYPES.md | 2 +- .../libs/interop/M-ESCAPE-HATCHES.md | 2 +- .../libs/resilience/M-AVOID-STATICS.md | 2 +- .../libs/resilience/M-MOCKABLE-SYSCALLS.md | 2 +- .../libs/resilience/M-NO-GLOB-REEXPORTS.md | 2 +- .../libs/resilience/M-STRONG-TYPES.md | 2 +- src/guidelines/libs/resilience/M-TEST-UTIL.md | 2 +- src/guidelines/libs/ux/M-AVOID-WRAPPERS.md | 2 +- src/guidelines/libs/ux/M-DI-HIERARCHY.md | 2 +- .../libs/ux/M-ERRORS-CANONICAL-STRUCTS.md | 2 +- .../libs/ux/M-ESSENTIAL-FN-INHERENT.md | 2 +- src/guidelines/libs/ux/M-IMPL-ASREF.md | 2 +- src/guidelines/libs/ux/M-IMPL-IO.md | 2 +- src/guidelines/libs/ux/M-IMPL-RANGEBOUNDS.md | 2 +- src/guidelines/libs/ux/M-INIT-BUILDER.md | 2 +- src/guidelines/libs/ux/M-INIT-CASCADED.md | 2 +- .../libs/ux/M-SIMPLE-ABSTRACTIONS.md | 2 +- src/guidelines/performance/M-HOTPATH.md | 2 +- src/guidelines/performance/M-THROUGHPUT.md | 2 +- src/guidelines/performance/M-YIELD-POINTS.md | 2 +- src/guidelines/safety/M-UNSAFE-IMPLIES-UB.md | 2 +- src/guidelines/safety/M-UNSAFE.md | 2 +- src/guidelines/safety/M-UNSOUND.md | 2 +- src/guidelines/universal/M-CONCISE-NAMES.md | 2 +- .../universal/M-DOCUMENTED-MAGIC.md | 2 +- .../universal/M-LINT-OVERRIDE-EXPECT.md | 2 +- src/guidelines/universal/M-LOG-STRUCTURED.md | 2 +- src/guidelines/universal/M-PANIC-IS-STOP.md | 2 +- src/guidelines/universal/M-PANIC-ON-BUG.md | 2 +- src/guidelines/universal/M-PUBLIC-DEBUG.md | 2 +- src/guidelines/universal/M-PUBLIC-DISPLAY.md | 2 +- src/guidelines/universal/M-REGULAR-FN.md | 2 +- src/guidelines/universal/M-SMALLER-CRATES.md | 2 +- .../universal/M-STATIC-VERIFICATION.md | 2 +- .../universal/M-UPSTREAM-GUIDELINES.md | 2 +- 47 files changed, 92 insertions(+), 92 deletions(-) diff --git a/src/guidelines/ai/M-DESIGN-FOR-AI.md b/src/guidelines/ai/M-DESIGN-FOR-AI.md index 6924c7e..9303ed6 100644 --- a/src/guidelines/ai/M-DESIGN-FOR-AI.md +++ b/src/guidelines/ai/M-DESIGN-FOR-AI.md @@ -1,6 +1,6 @@  -## 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 } To maximize the utility you get from letting agents work in your code base. 0.1 diff --git a/src/guidelines/apps/M-APP-ERROR.md b/src/guidelines/apps/M-APP-ERROR.md index ac64c5b..3214b9d 100644 --- a/src/guidelines/apps/M-APP-ERROR.md +++ b/src/guidelines/apps/M-APP-ERROR.md @@ -1,6 +1,6 @@  -## Applications may use Anyhow or Derivatives (M-APP-ERROR) { #M-APP-ERROR } +## Applications may use Anyhow or derivatives (M-APP-ERROR) { #M-APP-ERROR } To simplify application-level error handling. 0.1 diff --git a/src/guidelines/apps/M-MIMALLOC-APPS.md b/src/guidelines/apps/M-MIMALLOC-APPS.md index 9f9ef0e..7598c48 100644 --- a/src/guidelines/apps/M-MIMALLOC-APPS.md +++ b/src/guidelines/apps/M-MIMALLOC-APPS.md @@ -1,6 +1,6 @@  -## Use Mimalloc for Apps (M-MIMALLOC-APPS) { #M-MIMALLOC-APPS } +## Use mimalloc for apps (M-MIMALLOC-APPS) { #M-MIMALLOC-APPS } To get significant performance for free. 0.1 diff --git a/src/guidelines/checklist/README.md b/src/guidelines/checklist/README.md index 45683a2..f51cd58 100644 --- a/src/guidelines/checklist/README.md +++ b/src/guidelines/checklist/README.md @@ -3,64 +3,64 @@ # Checklist - **Universal** - - [ ] Follow the Upstream Guidelines ([M-UPSTREAM-GUIDELINES]) - - [ ] Use Static Verification ([M-STATIC-VERIFICATION]) - - [ ] Lint Overrides Should Use `#[expect]` ([M-LINT-OVERRIDE-EXPECT]) - - [ ] Public Types are Debug ([M-PUBLIC-DEBUG]) - - [ ] Public Types Meant to be Read are Display ([M-PUBLIC-DISPLAY]) - - [ ] If in Doubt, Split the Crate ([M-SMALLER-CRATES]) - - [ ] Names are Free of Weasel Words ([M-CONCISE-NAMES]) - - [ ] Prefer Regular over Associated Functions ([M-REGULAR-FN]) - - [ ] Panic Means 'Stop the Program' ([M-PANIC-IS-STOP]) - - [ ] Detected Programming Bugs are Panics, Not Errors ([M-PANIC-ON-BUG]) - - [ ] All Magic Values and Behaviors are Documented ([M-DOCUMENTED-MAGIC]) - - [ ] Use Structured Logging with Message Templates ([M-LOG-STRUCTURED]) + - [ ] Follow the upstream guidelines ([M-UPSTREAM-GUIDELINES]) + - [ ] Use static verification ([M-STATIC-VERIFICATION]) + - [ ] Lint overrides should use `#[expect]` ([M-LINT-OVERRIDE-EXPECT]) + - [ ] Public types are Debug ([M-PUBLIC-DEBUG]) + - [ ] Public types meant to be read are Display ([M-PUBLIC-DISPLAY]) + - [ ] If in doubt, split the crate ([M-SMALLER-CRATES]) + - [ ] Names are free of weasel words ([M-CONCISE-NAMES]) + - [ ] Prefer regular over associated functions ([M-REGULAR-FN]) + - [ ] Panic means 'stop the program' ([M-PANIC-IS-STOP]) + - [ ] Detected programming bugs are panics, not errors ([M-PANIC-ON-BUG]) + - [ ] Magic values are documented ([M-DOCUMENTED-MAGIC]) + - [ ] Use structured logging with message templates ([M-LOG-STRUCTURED]) - **Library / Interoperability** - [ ] Types are Send ([M-TYPES-SEND]) - - [ ] Native Escape Hatches ([M-ESCAPE-HATCHES]) - - [ ] Don't Leak External Types ([M-DONT-LEAK-TYPES]) + - [ ] Native escape hatches ([M-ESCAPE-HATCHES]) + - [ ] Don't leak external types ([M-DONT-LEAK-TYPES]) - **Library / UX** - - [ ] Abstractions Don't Visibly Nest ([M-SIMPLE-ABSTRACTIONS]) - - [ ] Avoid Smart Pointers and Wrappers in APIs ([M-AVOID-WRAPPERS]) - - [ ] Prefer Types over Generics, Generics over Dyn Traits ([M-DI-HIERARCHY]) - - [ ] Error are Canonical Structs ([M-ERRORS-CANONICAL-STRUCTS]) - - [ ] Complex Type Construction has Builders ([M-INIT-BUILDER]) - - [ ] Complex Type Initialization Hierarchies are Cascaded ([M-INIT-CASCADED]) + - [ ] Abstractions don't visibly nest ([M-SIMPLE-ABSTRACTIONS]) + - [ ] Avoid smart pointers and wrappers in APIs ([M-AVOID-WRAPPERS]) + - [ ] Prefer types over generics, generics over dyn traits ([M-DI-HIERARCHY]) + - [ ] Errors are canonical structs ([M-ERRORS-CANONICAL-STRUCTS]) + - [ ] Complex type construction has builders ([M-INIT-BUILDER]) + - [ ] Complex type initialization hierarchies are cascaded ([M-INIT-CASCADED]) - [ ] Services are Clone ([M-SERVICES-CLONE]) - - [ ] Accept `impl AsRef<>` Where Feasible ([M-IMPL-ASREF]) - - [ ] Accept `impl RangeBounds<>` Where Feasible ([M-IMPL-RANGEBOUNDS]) - - [ ] Accept `impl 'IO'` Where Feasible ('Sans IO') ([M-IMPL-IO]) - - [ ] Essential Functionality Should be Inherent ([M-ESSENTIAL-FN-INHERENT]) + - [ ] Accept `impl AsRef<>` where feasible ([M-IMPL-ASREF]) + - [ ] Accept `impl RangeBounds<>` where feasible ([M-IMPL-RANGEBOUNDS]) + - [ ] Accept `impl 'IO'` where feasible ('sans IO') ([M-IMPL-IO]) + - [ ] Essential functionality should be inherent ([M-ESSENTIAL-FN-INHERENT]) - **Library / Resilience** - - [ ] I/O and System Calls Are Mockable ([M-MOCKABLE-SYSCALLS]) - - [ ] Test Utilities are Feature Gated ([M-TEST-UTIL]) - - [ ] Use the Proper Type Family ([M-STRONG-TYPES]) - - [ ] Don't Glob Re-Export Items ([M-NO-GLOB-REEXPORTS]) - - [ ] Avoid Statics ([M-AVOID-STATICS]) + - [ ] I/O and system calls are mockable ([M-MOCKABLE-SYSCALLS]) + - [ ] Test utilities are feature gated ([M-TEST-UTIL]) + - [ ] Use the proper type family ([M-STRONG-TYPES]) + - [ ] Don't glob re-export items ([M-NO-GLOB-REEXPORTS]) + - [ ] Avoid statics ([M-AVOID-STATICS]) - **Library / Building** - - [ ] Libraries Work Out of the Box ([M-OOBE]) - - [ ] Native `-sys` Crates Compile Without Dependencies ([M-SYS-CRATES]) - - [ ] Features are Additive ([M-FEATURES-ADDITIVE]) + - [ ] Libraries work out of the box ([M-OOBE]) + - [ ] Native `-sys` crates compile without dependencies ([M-SYS-CRATES]) + - [ ] Features are additive ([M-FEATURES-ADDITIVE]) - **Applications** - - [ ] Use Mimalloc for Apps ([M-MIMALLOC-APP]) - - [ ] Applications may use Anyhow or Derivatives ([M-APP-ERROR]) + - [ ] Use mimalloc for apps ([M-MIMALLOC-APP]) + - [ ] Applications may use Anyhow or derivatives ([M-APP-ERROR]) - **FFI** - - [ ] Isolate DLL State Between FFI Libraries ([M-ISOLATE-DLL-STATE]) + - [ ] Isolate DLL state between FFI libraries ([M-ISOLATE-DLL-STATE]) - **Safety** - - [ ] Unsafe Needs Reason, Should be Avoided ([M-UNSAFE]) - - [ ] Unsafe Implies Undefined Behavior ([M-UNSAFE-IMPLIES-UB]) - - [ ] All Code Must be Sound ([M-UNSOUND]) + - [ ] Unsafe needs reason, should be avoided ([M-UNSAFE]) + - [ ] Unsafe implies undefined behavior ([M-UNSAFE-IMPLIES-UB]) + - [ ] All code must be sound ([M-UNSOUND]) - **Performance** - - [ ] Optimize for Throughput, Avoid Empty Cycles ([M-THROUGHPUT]) - - [ ] Identify, Profile, Optimize the Hot Path Early ([M-HOTPATH]) - - [ ] Long-Running Tasks Should Have Yield Points. ([M-YIELD-POINTS]) + - [ ] Optimize for throughput, avoid empty cycles ([M-THROUGHPUT]) + - [ ] Identify, profile, optimize the hot path early ([M-HOTPATH]) + - [ ] Long-running tasks should have yield points ([M-YIELD-POINTS]) - **Documentation** - - [ ] First Sentence is One Line; Approx. 15 Words ([M-FIRST-DOC-SENTENCE]) - - [ ] Has Module Documentation ([M-MODULE-DOCS]) - - [ ] Documentation Has Canonical Sections ([M-CANONICAL-DOCS]) - - [ ] Mark `pub use` Items with `#[doc(inline)]` ([M-DOC-INLINE]) + - [ ] First sentence is one line; approx. 15 words ([M-FIRST-DOC-SENTENCE]) + - [ ] Has comprehensive module documentation ([M-MODULE-DOCS]) + - [ ] Documentation has canonical sections ([M-CANONICAL-DOCS]) + - [ ] Mark `pub use` items with `#[doc(inline)]` ([M-DOC-INLINE]) - **AI** - - [ ] Design with AI use in Mind ([M-DESIGN-FOR-AI]) + - [ ] Design with AI use in mind ([M-DESIGN-FOR-AI]) [M-UPSTREAM-GUIDELINES]: ../universal/#M-UPSTREAM-GUIDELINES diff --git a/src/guidelines/docs/M-CANONICAL-DOCS.md b/src/guidelines/docs/M-CANONICAL-DOCS.md index b6017ca..f9b8538 100644 --- a/src/guidelines/docs/M-CANONICAL-DOCS.md +++ b/src/guidelines/docs/M-CANONICAL-DOCS.md @@ -1,6 +1,6 @@  -## Documentation Has Canonical Sections (M-CANONICAL-DOCS) { #M-CANONICAL-DOCS } +## Documentation has canonical sections (M-CANONICAL-DOCS) { #M-CANONICAL-DOCS } To follow established and expected Rust best practices. 1.0 diff --git a/src/guidelines/docs/M-DOC-INLINE.md b/src/guidelines/docs/M-DOC-INLINE.md index 20592a0..af9edea 100644 --- a/src/guidelines/docs/M-DOC-INLINE.md +++ b/src/guidelines/docs/M-DOC-INLINE.md @@ -1,6 +1,6 @@  -## Mark `pub use` Items with `#[doc(inline)]` (M-DOC-INLINE) { #M-DOC-INLINE } +## Mark `pub use` items with `#[doc(inline)]` (M-DOC-INLINE) { #M-DOC-INLINE } To make re-exported items 'fit in' with their non re-exported siblings. 1.0 diff --git a/src/guidelines/docs/M-FIRST-DOC-SENTENCE.md b/src/guidelines/docs/M-FIRST-DOC-SENTENCE.md index 727f22b..08f89b6 100644 --- a/src/guidelines/docs/M-FIRST-DOC-SENTENCE.md +++ b/src/guidelines/docs/M-FIRST-DOC-SENTENCE.md @@ -1,6 +1,6 @@  -## First Sentence is One Line; Approx. 15 Words (M-FIRST-DOC-SENTENCE) { #M-FIRST-DOC-SENTENCE } +## First sentence is one line; approx. 15 words (M-FIRST-DOC-SENTENCE) { #M-FIRST-DOC-SENTENCE } To make API docs easily skimmable. 1.0 diff --git a/src/guidelines/docs/M-MODULE-DOCS.md b/src/guidelines/docs/M-MODULE-DOCS.md index 2d49ab6..4694c11 100644 --- a/src/guidelines/docs/M-MODULE-DOCS.md +++ b/src/guidelines/docs/M-MODULE-DOCS.md @@ -1,6 +1,6 @@  -## Has Comprehensive Module Documentation (M-MODULE-DOCS) { #M-MODULE-DOCS } +## Has comprehensive module documentation (M-MODULE-DOCS) { #M-MODULE-DOCS } To allow for better API docs navigation. 1.1 diff --git a/src/guidelines/ffi/M-ISOLATE-DLL-STATE.md b/src/guidelines/ffi/M-ISOLATE-DLL-STATE.md index fda7b3c..6761a71 100644 --- a/src/guidelines/ffi/M-ISOLATE-DLL-STATE.md +++ b/src/guidelines/ffi/M-ISOLATE-DLL-STATE.md @@ -1,6 +1,6 @@  -## Isolate DLL State Between FFI Libraries (M-ISOLATE-DLL-STATE) { #M-ISOLATE-DLL-STATE } +## Isolate DLL state between FFI libraries (M-ISOLATE-DLL-STATE) { #M-ISOLATE-DLL-STATE } To prevent data corruption and undefined behavior. 0.1 diff --git a/src/guidelines/libs/building/M-FEATURES-ADDITIVE.md b/src/guidelines/libs/building/M-FEATURES-ADDITIVE.md index e463ced..4ff4a1c 100644 --- a/src/guidelines/libs/building/M-FEATURES-ADDITIVE.md +++ b/src/guidelines/libs/building/M-FEATURES-ADDITIVE.md @@ -1,6 +1,6 @@  -## Features are Additive (M-FEATURES-ADDITIVE) { #M-FEATURES-ADDITIVE } +## Features are additive (M-FEATURES-ADDITIVE) { #M-FEATURES-ADDITIVE } To prevent compilation breakage in large and complex projects. 1.0 diff --git a/src/guidelines/libs/building/M-OOBE.md b/src/guidelines/libs/building/M-OOBE.md index 5b47d80..1f42443 100644 --- a/src/guidelines/libs/building/M-OOBE.md +++ b/src/guidelines/libs/building/M-OOBE.md @@ -1,6 +1,6 @@  -## Libraries Work Out of the Box (M-OOBE) { #M-OOBE } +## Libraries work out of the box (M-OOBE) { #M-OOBE } To be easily adoptable by the Rust ecosystem. 1.0 diff --git a/src/guidelines/libs/building/M-SYS-CRATES.md b/src/guidelines/libs/building/M-SYS-CRATES.md index 3777311..c680f1f 100644 --- a/src/guidelines/libs/building/M-SYS-CRATES.md +++ b/src/guidelines/libs/building/M-SYS-CRATES.md @@ -1,6 +1,6 @@  -## Native `-sys` Crates Compile Without Dependencies (M-SYS-CRATES) { #M-SYS-CRATES } +## Native `-sys` crates compile without dependencies (M-SYS-CRATES) { #M-SYS-CRATES } To have libraries that 'just work' on all platforms. 0.2 diff --git a/src/guidelines/libs/interop/M-DONT-LEAK-TYPES.md b/src/guidelines/libs/interop/M-DONT-LEAK-TYPES.md index f8b8474..5218a41 100644 --- a/src/guidelines/libs/interop/M-DONT-LEAK-TYPES.md +++ b/src/guidelines/libs/interop/M-DONT-LEAK-TYPES.md @@ -1,6 +1,6 @@  -## Don't Leak External Types (M-DONT-LEAK-TYPES) { #M-DONT-LEAK-TYPES } +## Don't leak external types (M-DONT-LEAK-TYPES) { #M-DONT-LEAK-TYPES } To prevent accidental breakage and long-term maintenance cost. 0.1 diff --git a/src/guidelines/libs/interop/M-ESCAPE-HATCHES.md b/src/guidelines/libs/interop/M-ESCAPE-HATCHES.md index f434b93..de501e8 100644 --- a/src/guidelines/libs/interop/M-ESCAPE-HATCHES.md +++ b/src/guidelines/libs/interop/M-ESCAPE-HATCHES.md @@ -1,6 +1,6 @@  -## Native Escape Hatches (M-ESCAPE-HATCHES) { #M-ESCAPE-HATCHES } +## Native escape hatches (M-ESCAPE-HATCHES) { #M-ESCAPE-HATCHES } To allow users to work around unsupported use cases until alternatives are available. 0.1 diff --git a/src/guidelines/libs/resilience/M-AVOID-STATICS.md b/src/guidelines/libs/resilience/M-AVOID-STATICS.md index ebe8825..3242828 100644 --- a/src/guidelines/libs/resilience/M-AVOID-STATICS.md +++ b/src/guidelines/libs/resilience/M-AVOID-STATICS.md @@ -1,6 +1,6 @@  -## Avoid Statics (M-AVOID-STATICS) { #M-AVOID-STATICS } +## Avoid statics (M-AVOID-STATICS) { #M-AVOID-STATICS } To prevent consistency and correctness issues between crate versions. 1.0 diff --git a/src/guidelines/libs/resilience/M-MOCKABLE-SYSCALLS.md b/src/guidelines/libs/resilience/M-MOCKABLE-SYSCALLS.md index 9d0aaee..f0cf22a 100644 --- a/src/guidelines/libs/resilience/M-MOCKABLE-SYSCALLS.md +++ b/src/guidelines/libs/resilience/M-MOCKABLE-SYSCALLS.md @@ -1,6 +1,6 @@  -## I/O and System Calls Are Mockable (M-MOCKABLE-SYSCALLS) { #M-MOCKABLE-SYSCALLS } +## I/O and system calls are mockable (M-MOCKABLE-SYSCALLS) { #M-MOCKABLE-SYSCALLS } To make otherwise hard-to-evoke edge cases testable. 0.2 diff --git a/src/guidelines/libs/resilience/M-NO-GLOB-REEXPORTS.md b/src/guidelines/libs/resilience/M-NO-GLOB-REEXPORTS.md index ef44a65..665ca65 100644 --- a/src/guidelines/libs/resilience/M-NO-GLOB-REEXPORTS.md +++ b/src/guidelines/libs/resilience/M-NO-GLOB-REEXPORTS.md @@ -1,6 +1,6 @@  -## Don't Glob Re-Export Items (M-NO-GLOB-REEXPORTS) { #M-NO-GLOB-REEXPORTS } +## Don't glob re-export items (M-NO-GLOB-REEXPORTS) { #M-NO-GLOB-REEXPORTS } To prevent accidentally leaking unintended types. 1.0 diff --git a/src/guidelines/libs/resilience/M-STRONG-TYPES.md b/src/guidelines/libs/resilience/M-STRONG-TYPES.md index 6d449ba..945b01f 100644 --- a/src/guidelines/libs/resilience/M-STRONG-TYPES.md +++ b/src/guidelines/libs/resilience/M-STRONG-TYPES.md @@ -1,6 +1,6 @@  -## Use the Proper Type Family (M-STRONG-TYPES) { #M-STRONG-TYPES } +## Use the proper type family (M-STRONG-TYPES) { #M-STRONG-TYPES } To have and maintain the right data and safety variants, at the right time. 1.0 diff --git a/src/guidelines/libs/resilience/M-TEST-UTIL.md b/src/guidelines/libs/resilience/M-TEST-UTIL.md index 54c913b..c55660e 100644 --- a/src/guidelines/libs/resilience/M-TEST-UTIL.md +++ b/src/guidelines/libs/resilience/M-TEST-UTIL.md @@ -1,6 +1,6 @@  -## Test Utilities are Feature Gated (M-TEST-UTIL) { #M-TEST-UTIL } +## Test utilities are feature gated (M-TEST-UTIL) { #M-TEST-UTIL } To prevent production builds from accidentally bypassing safety checks. 0.2 diff --git a/src/guidelines/libs/ux/M-AVOID-WRAPPERS.md b/src/guidelines/libs/ux/M-AVOID-WRAPPERS.md index d7bd82d..a7f6f28 100644 --- a/src/guidelines/libs/ux/M-AVOID-WRAPPERS.md +++ b/src/guidelines/libs/ux/M-AVOID-WRAPPERS.md @@ -1,6 +1,6 @@  -## Avoid Smart Pointers and Wrappers in APIs (M-AVOID-WRAPPERS) { #M-AVOID-WRAPPERS } +## Avoid smart pointers and wrappers in APIs (M-AVOID-WRAPPERS) { #M-AVOID-WRAPPERS } To reduce cognitive load and improve API ergonomics. 1.0 diff --git a/src/guidelines/libs/ux/M-DI-HIERARCHY.md b/src/guidelines/libs/ux/M-DI-HIERARCHY.md index af51701..3a34900 100644 --- a/src/guidelines/libs/ux/M-DI-HIERARCHY.md +++ b/src/guidelines/libs/ux/M-DI-HIERARCHY.md @@ -1,6 +1,6 @@  -## Prefer Types over Generics, Generics over Dyn Traits (M-DI-HIERARCHY) { #M-DI-HIERARCHY } +## Prefer types over generics, generics over dyn traits (M-DI-HIERARCHY) { #M-DI-HIERARCHY } To prevent patterns that don't compose, and design lock-in. 0.1 diff --git a/src/guidelines/libs/ux/M-ERRORS-CANONICAL-STRUCTS.md b/src/guidelines/libs/ux/M-ERRORS-CANONICAL-STRUCTS.md index 03c3814..137c7a0 100644 --- a/src/guidelines/libs/ux/M-ERRORS-CANONICAL-STRUCTS.md +++ b/src/guidelines/libs/ux/M-ERRORS-CANONICAL-STRUCTS.md @@ -1,6 +1,6 @@  -## Error are Canonical Structs (M-ERRORS-CANONICAL-STRUCTS) { #M-ERRORS-CANONICAL-STRUCTS } +## Errors are canonical structs (M-ERRORS-CANONICAL-STRUCTS) { #M-ERRORS-CANONICAL-STRUCTS } To harmonize the behavior of error types, and provide a consistent error handling. 1.0 diff --git a/src/guidelines/libs/ux/M-ESSENTIAL-FN-INHERENT.md b/src/guidelines/libs/ux/M-ESSENTIAL-FN-INHERENT.md index 30d30bb..47a5586 100644 --- a/src/guidelines/libs/ux/M-ESSENTIAL-FN-INHERENT.md +++ b/src/guidelines/libs/ux/M-ESSENTIAL-FN-INHERENT.md @@ -1,6 +1,6 @@  -## Essential Functionality Should be Inherent (M-ESSENTIAL-FN-INHERENT) { #M-ESSENTIAL-FN-INHERENT } +## Essential functionality should be inherent (M-ESSENTIAL-FN-INHERENT) { #M-ESSENTIAL-FN-INHERENT } To make essential functionality easily discoverable. 1.0 diff --git a/src/guidelines/libs/ux/M-IMPL-ASREF.md b/src/guidelines/libs/ux/M-IMPL-ASREF.md index ec79752..473a846 100644 --- a/src/guidelines/libs/ux/M-IMPL-ASREF.md +++ b/src/guidelines/libs/ux/M-IMPL-ASREF.md @@ -1,6 +1,6 @@  -## Accept `impl AsRef<>` Where Feasible (M-IMPL-ASREF) { #M-IMPL-ASREF } +## Accept `impl AsRef<>` where feasible (M-IMPL-ASREF) { #M-IMPL-ASREF } To give users flexibility calling in with their own types. 1.0 diff --git a/src/guidelines/libs/ux/M-IMPL-IO.md b/src/guidelines/libs/ux/M-IMPL-IO.md index 0817b57..e443dbd 100644 --- a/src/guidelines/libs/ux/M-IMPL-IO.md +++ b/src/guidelines/libs/ux/M-IMPL-IO.md @@ -1,6 +1,6 @@  -## Accept `impl 'IO'` Where Feasible ('Sans IO') (M-IMPL-IO) { #M-IMPL-IO } +## Accept `impl 'IO'` where feasible ('sans IO') (M-IMPL-IO) { #M-IMPL-IO } To untangle business logic from I/O logic, and have N*M composability. 0.1 diff --git a/src/guidelines/libs/ux/M-IMPL-RANGEBOUNDS.md b/src/guidelines/libs/ux/M-IMPL-RANGEBOUNDS.md index c0d6f76..df886c6 100644 --- a/src/guidelines/libs/ux/M-IMPL-RANGEBOUNDS.md +++ b/src/guidelines/libs/ux/M-IMPL-RANGEBOUNDS.md @@ -1,6 +1,6 @@  -## Accept `impl RangeBounds<>` Where Feasible (M-IMPL-RANGEBOUNDS) { #M-IMPL-RANGEBOUNDS } +## Accept `impl RangeBounds<>` where feasible (M-IMPL-RANGEBOUNDS) { #M-IMPL-RANGEBOUNDS } To give users flexibility and clarity when specifying ranges. 1.0 diff --git a/src/guidelines/libs/ux/M-INIT-BUILDER.md b/src/guidelines/libs/ux/M-INIT-BUILDER.md index 32bb14e..eb86471 100644 --- a/src/guidelines/libs/ux/M-INIT-BUILDER.md +++ b/src/guidelines/libs/ux/M-INIT-BUILDER.md @@ -1,6 +1,6 @@  -## Complex Type Construction has Builders (M-INIT-BUILDER) { #M-INIT-BUILDER } +## Complex type construction has builders (M-INIT-BUILDER) { #M-INIT-BUILDER } To future-proof type construction in complex scenarios. 0.3 diff --git a/src/guidelines/libs/ux/M-INIT-CASCADED.md b/src/guidelines/libs/ux/M-INIT-CASCADED.md index 0dd25cd..ffbe6b3 100644 --- a/src/guidelines/libs/ux/M-INIT-CASCADED.md +++ b/src/guidelines/libs/ux/M-INIT-CASCADED.md @@ -1,6 +1,6 @@  -## Complex Type Initialization Hierarchies are Cascaded (M-INIT-CASCADED) { #M-INIT-CASCADED } +## Complex type initialization hierarchies are cascaded (M-INIT-CASCADED) { #M-INIT-CASCADED } To prevent misuse and accidental parameter mix ups. 1.0 diff --git a/src/guidelines/libs/ux/M-SIMPLE-ABSTRACTIONS.md b/src/guidelines/libs/ux/M-SIMPLE-ABSTRACTIONS.md index f0449dd..182bd05 100644 --- a/src/guidelines/libs/ux/M-SIMPLE-ABSTRACTIONS.md +++ b/src/guidelines/libs/ux/M-SIMPLE-ABSTRACTIONS.md @@ -1,6 +1,6 @@  -## Abstractions Don't Visibly Nest (M-SIMPLE-ABSTRACTIONS) { #M-SIMPLE-ABSTRACTIONS } +## Abstractions don't visibly nest (M-SIMPLE-ABSTRACTIONS) { #M-SIMPLE-ABSTRACTIONS } To prevent cognitive load and a bad out of the box UX. 0.1 diff --git a/src/guidelines/performance/M-HOTPATH.md b/src/guidelines/performance/M-HOTPATH.md index e6b3550..2d6630d 100644 --- a/src/guidelines/performance/M-HOTPATH.md +++ b/src/guidelines/performance/M-HOTPATH.md @@ -1,6 +1,6 @@  -## Identify, Profile, Optimize the Hot Path Early (M-HOTPATH) { #M-HOTPATH } +## Identify, profile, optimize the hot path early (M-HOTPATH) { #M-HOTPATH } To end up with high performance code. 0.1 diff --git a/src/guidelines/performance/M-THROUGHPUT.md b/src/guidelines/performance/M-THROUGHPUT.md index 4d224c7..d574cfd 100644 --- a/src/guidelines/performance/M-THROUGHPUT.md +++ b/src/guidelines/performance/M-THROUGHPUT.md @@ -1,6 +1,6 @@  -## Optimize for Throughput, Avoid Empty Cycles (M-THROUGHPUT) { #M-THROUGHPUT } +## Optimize for throughput, avoid empty cycles (M-THROUGHPUT) { #M-THROUGHPUT } To ensure COGS savings at scale. 0.1 diff --git a/src/guidelines/performance/M-YIELD-POINTS.md b/src/guidelines/performance/M-YIELD-POINTS.md index edbbae9..91f6d7d 100644 --- a/src/guidelines/performance/M-YIELD-POINTS.md +++ b/src/guidelines/performance/M-YIELD-POINTS.md @@ -1,6 +1,6 @@  -## Long-Running Tasks Should Have Yield Points. (M-YIELD-POINTS) { #M-YIELD-POINTS } +## Long-running tasks should have yield points (M-YIELD-POINTS) { #M-YIELD-POINTS } To ensure you don't starve other tasks of CPU time. 0.2 diff --git a/src/guidelines/safety/M-UNSAFE-IMPLIES-UB.md b/src/guidelines/safety/M-UNSAFE-IMPLIES-UB.md index b20c445..9015832 100644 --- a/src/guidelines/safety/M-UNSAFE-IMPLIES-UB.md +++ b/src/guidelines/safety/M-UNSAFE-IMPLIES-UB.md @@ -1,6 +1,6 @@  -## Unsafe Implies Undefined Behavior (M-UNSAFE-IMPLIES-UB) { #M-UNSAFE-IMPLIES-UB } +## Unsafe implies undefined behavior (M-UNSAFE-IMPLIES-UB) { #M-UNSAFE-IMPLIES-UB } To ensure semantic consistency and prevent warning fatigue. 1.0 diff --git a/src/guidelines/safety/M-UNSAFE.md b/src/guidelines/safety/M-UNSAFE.md index fec7f9e..6652540 100644 --- a/src/guidelines/safety/M-UNSAFE.md +++ b/src/guidelines/safety/M-UNSAFE.md @@ -1,6 +1,6 @@  -## Unsafe Needs Reason, Should be Avoided (M-UNSAFE) { #M-UNSAFE } +## Unsafe needs reason, should be avoided (M-UNSAFE) { #M-UNSAFE } To prevent undefined behavior, attack surface, and similar 'happy little accidents'. 0.2 diff --git a/src/guidelines/safety/M-UNSOUND.md b/src/guidelines/safety/M-UNSOUND.md index bdd6cc6..f11a5f1 100644 --- a/src/guidelines/safety/M-UNSOUND.md +++ b/src/guidelines/safety/M-UNSOUND.md @@ -1,6 +1,6 @@  -## All Code Must be Sound (M-UNSOUND) { #M-UNSOUND } +## All code must be sound (M-UNSOUND) { #M-UNSOUND } To prevent unexpected runtime behavior, leading to potential bugs and incompatibilities. 1.0 diff --git a/src/guidelines/universal/M-CONCISE-NAMES.md b/src/guidelines/universal/M-CONCISE-NAMES.md index 802c5c6..2c8b211 100644 --- a/src/guidelines/universal/M-CONCISE-NAMES.md +++ b/src/guidelines/universal/M-CONCISE-NAMES.md @@ -1,6 +1,6 @@  -## Names are Free of Weasel Words (M-CONCISE-NAMES) { #M-CONCISE-NAMES } +## Names are free of weasel words (M-CONCISE-NAMES) { #M-CONCISE-NAMES } To improve readability. 1.0 diff --git a/src/guidelines/universal/M-DOCUMENTED-MAGIC.md b/src/guidelines/universal/M-DOCUMENTED-MAGIC.md index dddf313..a9d69c1 100644 --- a/src/guidelines/universal/M-DOCUMENTED-MAGIC.md +++ b/src/guidelines/universal/M-DOCUMENTED-MAGIC.md @@ -1,6 +1,6 @@  -## Magic Values are Documented (M-DOCUMENTED-MAGIC) { #M-DOCUMENTED-MAGIC } +## Magic values are documented (M-DOCUMENTED-MAGIC) { #M-DOCUMENTED-MAGIC } To ensure maintainability and prevent misunderstandings when refactoring. 1.0 diff --git a/src/guidelines/universal/M-LINT-OVERRIDE-EXPECT.md b/src/guidelines/universal/M-LINT-OVERRIDE-EXPECT.md index efb2951..3c456ea 100644 --- a/src/guidelines/universal/M-LINT-OVERRIDE-EXPECT.md +++ b/src/guidelines/universal/M-LINT-OVERRIDE-EXPECT.md @@ -1,6 +1,6 @@  -## Lint Overrides Should Use `#[expect]` (M-LINT-OVERRIDE-EXPECT) { #M-LINT-OVERRIDE-EXPECT } +## Lint overrides should use `#[expect]` (M-LINT-OVERRIDE-EXPECT) { #M-LINT-OVERRIDE-EXPECT } To prevent the accumulation of outdated lints. 1.0 diff --git a/src/guidelines/universal/M-LOG-STRUCTURED.md b/src/guidelines/universal/M-LOG-STRUCTURED.md index c0524a0..cb0a5a0 100644 --- a/src/guidelines/universal/M-LOG-STRUCTURED.md +++ b/src/guidelines/universal/M-LOG-STRUCTURED.md @@ -1,6 +1,6 @@ -## Use Structured Logging with Message Templates (M-LOG-STRUCTURED) { #M-LOG-STRUCTURED } +## Use structured logging with message templates (M-LOG-STRUCTURED) { #M-LOG-STRUCTURED } To minimize the cost of logging and to improve filtering capabilities. 0.1 diff --git a/src/guidelines/universal/M-PANIC-IS-STOP.md b/src/guidelines/universal/M-PANIC-IS-STOP.md index 191c0ee..0217d60 100644 --- a/src/guidelines/universal/M-PANIC-IS-STOP.md +++ b/src/guidelines/universal/M-PANIC-IS-STOP.md @@ -1,6 +1,6 @@  -## Panic Means 'Stop the Program' (M-PANIC-IS-STOP) { #M-PANIC-IS-STOP } +## Panic means 'stop the program' (M-PANIC-IS-STOP) { #M-PANIC-IS-STOP } To ensure soundness and predictability. 1.0 diff --git a/src/guidelines/universal/M-PANIC-ON-BUG.md b/src/guidelines/universal/M-PANIC-ON-BUG.md index c86d89e..22c2f90 100644 --- a/src/guidelines/universal/M-PANIC-ON-BUG.md +++ b/src/guidelines/universal/M-PANIC-ON-BUG.md @@ -1,6 +1,6 @@  -## Detected Programming Bugs are Panics, Not Errors (M-PANIC-ON-BUG) { #M-PANIC-ON-BUG } +## Detected programming bugs are panics, not errors (M-PANIC-ON-BUG) { #M-PANIC-ON-BUG } To avoid impossible error handling code and ensure runtime consistency. 1.0 diff --git a/src/guidelines/universal/M-PUBLIC-DEBUG.md b/src/guidelines/universal/M-PUBLIC-DEBUG.md index 38fc273..0caac46 100644 --- a/src/guidelines/universal/M-PUBLIC-DEBUG.md +++ b/src/guidelines/universal/M-PUBLIC-DEBUG.md @@ -1,6 +1,6 @@  -## Public Types are Debug (M-PUBLIC-DEBUG) { #M-PUBLIC-DEBUG } +## Public types are Debug (M-PUBLIC-DEBUG) { #M-PUBLIC-DEBUG } To simplify debugging and prevent leaking sensitive data. 1.0 diff --git a/src/guidelines/universal/M-PUBLIC-DISPLAY.md b/src/guidelines/universal/M-PUBLIC-DISPLAY.md index c42eefc..0cff515 100644 --- a/src/guidelines/universal/M-PUBLIC-DISPLAY.md +++ b/src/guidelines/universal/M-PUBLIC-DISPLAY.md @@ -1,6 +1,6 @@  -## Public Types Meant to be Read are Display (M-PUBLIC-DISPLAY) { #M-PUBLIC-DISPLAY } +## Public types meant to be read are Display (M-PUBLIC-DISPLAY) { #M-PUBLIC-DISPLAY } To improve usability. 1.0 diff --git a/src/guidelines/universal/M-REGULAR-FN.md b/src/guidelines/universal/M-REGULAR-FN.md index bc60869..52112ba 100644 --- a/src/guidelines/universal/M-REGULAR-FN.md +++ b/src/guidelines/universal/M-REGULAR-FN.md @@ -1,6 +1,6 @@  -## Prefer Regular over Associated Functions (M-REGULAR-FN) { #M-REGULAR-FN } +## Prefer regular over associated functions (M-REGULAR-FN) { #M-REGULAR-FN } To improve readability. 1.0 diff --git a/src/guidelines/universal/M-SMALLER-CRATES.md b/src/guidelines/universal/M-SMALLER-CRATES.md index 4cfdf60..653f2fe 100644 --- a/src/guidelines/universal/M-SMALLER-CRATES.md +++ b/src/guidelines/universal/M-SMALLER-CRATES.md @@ -1,6 +1,6 @@  -## If in Doubt, Split the Crate (M-SMALLER-CRATES) { #M-SMALLER-CRATES } +## If in doubt, split the crate (M-SMALLER-CRATES) { #M-SMALLER-CRATES } To improve compile times and modularity. 1.0 diff --git a/src/guidelines/universal/M-STATIC-VERIFICATION.md b/src/guidelines/universal/M-STATIC-VERIFICATION.md index 4ae45a8..d8dadb0 100644 --- a/src/guidelines/universal/M-STATIC-VERIFICATION.md +++ b/src/guidelines/universal/M-STATIC-VERIFICATION.md @@ -1,6 +1,6 @@  -## Use Static Verification (M-STATIC-VERIFICATION) { #M-STATIC-VERIFICATION } +## Use static verification (M-STATIC-VERIFICATION) { #M-STATIC-VERIFICATION } To ensure consistency and avoid common issues. 1.0 diff --git a/src/guidelines/universal/M-UPSTREAM-GUIDELINES.md b/src/guidelines/universal/M-UPSTREAM-GUIDELINES.md index 5764ef9..03b37a7 100644 --- a/src/guidelines/universal/M-UPSTREAM-GUIDELINES.md +++ b/src/guidelines/universal/M-UPSTREAM-GUIDELINES.md @@ -1,6 +1,6 @@  -## Follow the Upstream Guidelines (M-UPSTREAM-GUIDELINES) { #M-UPSTREAM-GUIDELINES } +## Follow the upstream guidelines (M-UPSTREAM-GUIDELINES) { #M-UPSTREAM-GUIDELINES } To avoid repeating mistakes the community has already learned from, and to have a codebase that does not surprise users and contributors. 1.0 From 4e5d0813c25e7ff0fdd73e2bea04be5b629e07db Mon Sep 17 00:00:00 2001 From: Ralf Biedert Date: Fri, 22 May 2026 15:32:50 +0200 Subject: [PATCH 05/10] Disable confusing nav sections. --- book.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/book.toml b/book.toml index 18bf7dc..12e91d4 100644 --- a/book.toml +++ b/book.toml @@ -7,6 +7,7 @@ src = "src" [output.html] additional-css = [ "style/tags.css", "style/fixes.css", "style/guideline-meta.css", "style/build-date.css" ] git-repository-url = "https://github.com/microsoft/rust-guidelines" +sidebar-header-nav = false [output.html.print] enable = true From 169c3f0b5a9558eeee9685afb3aa21c45cb5835f Mon Sep 17 00:00:00 2001 From: Ralf Biedert Date: Fri, 22 May 2026 15:33:17 +0200 Subject: [PATCH 06/10] 40+ more guidelines. --- src/SUMMARY.md | 2 + src/guidelines/ai/M-HUMAN-REVIEW.md | 19 ++++ .../ai/M-NO-META-DESIGN-DOCUMENTATION.md | 22 +++++ src/guidelines/ai/M-RUST-SHAPED.md | 22 +++++ src/guidelines/ai/M-SINGLE-ITEM-PATH.md | 32 ++++++ src/guidelines/ai/M-TAUTOLOGICAL-TESTS.md | 21 ++++ src/guidelines/ai/README.md | 5 + src/guidelines/apps/M-TARGET-CPU.md | 17 ++++ src/guidelines/apps/README.md | 1 + src/guidelines/checklist/README.md | 97 ++++++++++++++++++- src/guidelines/ffi/M-FFI-NAMING.md | 13 +++ src/guidelines/ffi/M-FFI-TRANSLATES.md | 51 ++++++++++ src/guidelines/ffi/README.md | 2 + .../libs/interop/M-FOREIGN-REEXPORTS.md | 14 +++ src/guidelines/libs/interop/README.md | 1 + .../libs/resilience/M-INTEGRATION-TESTS.md | 10 ++ .../libs/resilience/M-PANIC-CONTINUATION.md | 34 +++++++ .../libs/resilience/M-PANIC-MESSAGE.md | 16 +++ .../libs/resilience/M-STRONG-TYPES-GUARD.md | 36 +++++++ src/guidelines/libs/resilience/README.md | 4 + src/guidelines/libs/ux/M-ASYNC-FN.md | 14 +++ src/guidelines/libs/ux/M-BALANCED-MODULES.md | 17 ++++ src/guidelines/libs/ux/M-BUILD-RESULT.md | 15 +++ src/guidelines/libs/ux/M-COLLECTION-TRAITS.md | 16 +++ .../libs/ux/M-EXT-TRAITS-FOREIGN-ITEMS.md | 11 +++ src/guidelines/libs/ux/M-FROM-ERROR.md | 14 +++ src/guidelines/libs/ux/M-NO-PRELUDE.md | 30 ++++++ .../libs/ux/M-PARAMETER-CONSISTENCY.md | 14 +++ src/guidelines/libs/ux/M-PARAMETER-ORDER.md | 15 +++ src/guidelines/libs/ux/README.md | 9 ++ src/guidelines/macros/M-MACRO-HELPERS.md | 25 +++++ src/guidelines/macros/M-MACRO-LAST-RESORT.md | 20 ++++ src/guidelines/macros/M-MACRO-MAIN-CRATE.md | 17 ++++ src/guidelines/macros/M-MACROS-DONT-LIE.md | 26 +++++ src/guidelines/macros/M-MBE-OVER-PROC.md | 20 ++++ .../macros/M-PROC-HARDCODED-TYPES.md | 54 +++++++++++ src/guidelines/macros/M-PROC-IMPL.md | 30 ++++++ src/guidelines/macros/M-PROC-IMPLIED-ITEMS.md | 54 +++++++++++ src/guidelines/macros/README.md | 11 +++ .../performance/M-AVOID-INDIRECTION.md | 46 +++++++++ src/guidelines/performance/M-BOX-DST.md | 32 ++++++ src/guidelines/performance/M-FAST-HASHER.md | 18 ++++ .../performance/M-INITIAL-CAPACITY.md | 31 ++++++ src/guidelines/performance/M-LOG-OVERHEAD.md | 28 ++++++ src/guidelines/performance/M-MEM-REUSE.md | 48 +++++++++ src/guidelines/performance/M-SHRINK-TO-FIT.md | 22 +++++ src/guidelines/performance/README.md | 7 ++ src/guidelines/project/M-CARGO-WORKSPACE.md | 10 ++ .../project/M-CRATES-FLAT-FOLDER.md | 10 ++ .../project/M-CRATES-IN-WORKSPACE.md | 22 +++++ src/guidelines/project/M-LATEST-EDITION.md | 10 ++ src/guidelines/project/M-MSRV.md | 12 +++ src/guidelines/project/README.md | 9 ++ src/guidelines/universal/M-LOG-NOT-PRINT.md | 15 +++ src/guidelines/universal/M-SHORT-NAMES.md | 15 +++ .../{M-CONCISE-NAMES.md => M-WEASEL-WORDS.md} | 2 +- src/guidelines/universal/README.md | 4 +- 57 files changed, 1168 insertions(+), 4 deletions(-) create mode 100644 src/guidelines/ai/M-HUMAN-REVIEW.md create mode 100644 src/guidelines/ai/M-NO-META-DESIGN-DOCUMENTATION.md create mode 100644 src/guidelines/ai/M-RUST-SHAPED.md create mode 100644 src/guidelines/ai/M-SINGLE-ITEM-PATH.md create mode 100644 src/guidelines/ai/M-TAUTOLOGICAL-TESTS.md create mode 100644 src/guidelines/apps/M-TARGET-CPU.md create mode 100644 src/guidelines/ffi/M-FFI-NAMING.md create mode 100644 src/guidelines/ffi/M-FFI-TRANSLATES.md create mode 100644 src/guidelines/libs/interop/M-FOREIGN-REEXPORTS.md create mode 100644 src/guidelines/libs/resilience/M-INTEGRATION-TESTS.md create mode 100644 src/guidelines/libs/resilience/M-PANIC-CONTINUATION.md create mode 100644 src/guidelines/libs/resilience/M-PANIC-MESSAGE.md create mode 100644 src/guidelines/libs/resilience/M-STRONG-TYPES-GUARD.md create mode 100644 src/guidelines/libs/ux/M-ASYNC-FN.md create mode 100644 src/guidelines/libs/ux/M-BALANCED-MODULES.md create mode 100644 src/guidelines/libs/ux/M-BUILD-RESULT.md create mode 100644 src/guidelines/libs/ux/M-COLLECTION-TRAITS.md create mode 100644 src/guidelines/libs/ux/M-EXT-TRAITS-FOREIGN-ITEMS.md create mode 100644 src/guidelines/libs/ux/M-FROM-ERROR.md create mode 100644 src/guidelines/libs/ux/M-NO-PRELUDE.md create mode 100644 src/guidelines/libs/ux/M-PARAMETER-CONSISTENCY.md create mode 100644 src/guidelines/libs/ux/M-PARAMETER-ORDER.md create mode 100644 src/guidelines/macros/M-MACRO-HELPERS.md create mode 100644 src/guidelines/macros/M-MACRO-LAST-RESORT.md create mode 100644 src/guidelines/macros/M-MACRO-MAIN-CRATE.md create mode 100644 src/guidelines/macros/M-MACROS-DONT-LIE.md create mode 100644 src/guidelines/macros/M-MBE-OVER-PROC.md create mode 100644 src/guidelines/macros/M-PROC-HARDCODED-TYPES.md create mode 100644 src/guidelines/macros/M-PROC-IMPL.md create mode 100644 src/guidelines/macros/M-PROC-IMPLIED-ITEMS.md create mode 100644 src/guidelines/macros/README.md create mode 100644 src/guidelines/performance/M-AVOID-INDIRECTION.md create mode 100644 src/guidelines/performance/M-BOX-DST.md create mode 100644 src/guidelines/performance/M-FAST-HASHER.md create mode 100644 src/guidelines/performance/M-INITIAL-CAPACITY.md create mode 100644 src/guidelines/performance/M-LOG-OVERHEAD.md create mode 100644 src/guidelines/performance/M-MEM-REUSE.md create mode 100644 src/guidelines/performance/M-SHRINK-TO-FIT.md create mode 100644 src/guidelines/project/M-CARGO-WORKSPACE.md create mode 100644 src/guidelines/project/M-CRATES-FLAT-FOLDER.md create mode 100644 src/guidelines/project/M-CRATES-IN-WORKSPACE.md create mode 100644 src/guidelines/project/M-LATEST-EDITION.md create mode 100644 src/guidelines/project/M-MSRV.md create mode 100644 src/guidelines/project/README.md create mode 100644 src/guidelines/universal/M-LOG-NOT-PRINT.md create mode 100644 src/guidelines/universal/M-SHORT-NAMES.md rename src/guidelines/universal/{M-CONCISE-NAMES.md => M-WEASEL-WORDS.md} (96%) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index fc1ba13..5bb889b 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -9,10 +9,12 @@ - [UX](./guidelines/libs/ux/README.md) - [Resilience](./guidelines/libs/resilience/README.md) - [Building](./guidelines/libs/building/README.md) +- [Macros](./guidelines/macros/README.md) - [Applications](./guidelines/apps/README.md) - [FFI](./guidelines/ffi/README.md) - [Safety](./guidelines/safety/README.md) - [Performance](./guidelines/performance/README.md) +- [Project](./guidelines/project/README.md) - [Documentation](./guidelines/docs/README.md) - [AI](./guidelines/ai/README.md) diff --git a/src/guidelines/ai/M-HUMAN-REVIEW.md b/src/guidelines/ai/M-HUMAN-REVIEW.md new file mode 100644 index 0000000..564f731 --- /dev/null +++ b/src/guidelines/ai/M-HUMAN-REVIEW.md @@ -0,0 +1,19 @@ + + +## All agent-generated APIs require human review (M-HUMAN-REVIEW) { #M-HUMAN-REVIEW } + +To ensure API coherence, and adherence to project standards. +0.1 + +Agents can do a great job authoring APIs within minutes that would take you otherwise hours to complete, but they often do a poor job designing 'for the right thing', or silently drop requirements. + +Rust has advantage over many other languages of strong type system to force correctness at compile time, and design APIs that are fast and hard to misuse. Good API design can greatly aid in forcing a correct implementation. + +However, as APIs also define contracts between you and your users, bad choices can have viral effects (e.g., compare M-AVOID-WRAPPERS, M-AVOID-STATICS) and cannot easily be verified. + +Before submiting major PRs or releasing new APIs you and / or other human reviewers must check all guidelines and other requiemetns are adhered to, and the overall API looks reasonable. + +In particular ensure all public APIs follows these guidelines and M-UPSTREAM-GUIDELINES. You may use LLMs to point out where these guidelines are not met, but (until model fidelity improves) you cannot take the your agent's word that the guidelines are met. + + + diff --git a/src/guidelines/ai/M-NO-META-DESIGN-DOCUMENTATION.md b/src/guidelines/ai/M-NO-META-DESIGN-DOCUMENTATION.md new file mode 100644 index 0000000..32511a5 --- /dev/null +++ b/src/guidelines/ai/M-NO-META-DESIGN-DOCUMENTATION.md @@ -0,0 +1,22 @@ + + +## Avoid meta design documentation (M-NO-META-DESIGN-DOCUMENTATION) { #M-NO-META-DESIGN-DOCUMENTATION } + +to avoid confusing users with information not relevant to them. +0.1 + +Crate and module documentation must be free of meta design narratives that were only relevant during the creation of a crate. + +Agents frequently produce sections that describe how a change was designed, "why we picked X over Y" essays, and design journals inside user-facing documentation. These artifacts might be interesting diagnostics while working on the project, but they are mostly meaningless to end users. + +For example, an agent might append a self-report like this, summarizing which guidelines it claims to have followed: + +``` +| Rule | Applied | Where | +| --- | :---: | --- | +| M-SHORT-NAMES | ✅ | Shortened method names across the data-access and HTTP handler layers. | +| M-WEASEL-WORDS | ✅ | Removed weasel words from type and field names throughout the public API. | +| M-PUBLIC-DISPLAY | ✅ | Added `Display` impls for all user-facing identifier and error types. | +| M-ASYNC-FN | ✅ | Migrated I/O-facing APIs from `impl Future` returns to `async fn`. | +``` +This kind of content describes process, not behaviour, and goes stale over time. That said, it is of course perfectly reasonable to have a _Design Principles_ or similar section in the project's README, that on a high level describes the enduring architectural goals that are relevant to end users (e.g., a crate being allocation free, having an OSI architecture, or being designed with `#[no_std]` in mind). diff --git a/src/guidelines/ai/M-RUST-SHAPED.md b/src/guidelines/ai/M-RUST-SHAPED.md new file mode 100644 index 0000000..2b924ed --- /dev/null +++ b/src/guidelines/ai/M-RUST-SHAPED.md @@ -0,0 +1,22 @@ + + +## Rust code solves Rust problems (M-RUST-SHAPED) { #M-RUST-SHAPED } + +To ensure code is idiomatic. +0.1 + +When (automatically) porting C#, Java, C++, or similar code to Rust, technical constructs must not be copied 1-on-1. + +It is prudent to separate domain aspects from language aspects. Domain aspects address business problems. An algorithm to compute prime numbers or logic how to process 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 + +- error handling, +- management of task and threads, +- component abstractions and their lifetimes, +- ownership of parameters, +- and many others. + +While some language constructs simply don't translate at all (e.g., compared to C#, Rust does not have any meaningful reflection), while others are deceptively similar and might only bite months down the line (e.g., statics, compare M-AVOID-STATICS). + +As a rule of thumb, structs and their methods can have vaguely similar names, flows, input and outputs, as far as their business functionality is concerned. However, any striking technical similarity between Rust and { C#, Java, Python, ... } implementations is indicative of deeper architectural problems. diff --git a/src/guidelines/ai/M-SINGLE-ITEM-PATH.md b/src/guidelines/ai/M-SINGLE-ITEM-PATH.md new file mode 100644 index 0000000..a2eaa16 --- /dev/null +++ b/src/guidelines/ai/M-SINGLE-ITEM-PATH.md @@ -0,0 +1,32 @@ + + +## Items are only visible through one path (M-SINGLE-ITEM-PATH) { #M-SINGLE-ITEM-PATH } + +to avoid confusion and clutter offering the same type multiple times. +0.1 + +Public items within a crate should be reachable only through one path. For example some `crate::db::Connection` should not also be visible as `crate::Connection`: + +```rust +// Not OK +pub mod db { + pub struct Connection; +} + +pub use db::Connection; +``` + +This rule is often violated by agents creating or refactoring large code bases over several iterations. In an attempt to _simplify_ their task, they re-export items under a multiple paths, often previous ones before some change, instead of cleanly redesigning structures where it makes sense. + +Note this only targets the duplication of user-facing items. Within a crate it is acceptable (and often unavoidable) to see the same item multiple times as export trees are constructed: + +```rust +// OK +pub(crate) mod db { + pub struct Connection; +} + +pub use db::Connection; +``` + +Similarly, re-exports of foreign items are not covered by this rule, although they should follow M-ORIGINAL-CRATES. diff --git a/src/guidelines/ai/M-TAUTOLOGICAL-TESTS.md b/src/guidelines/ai/M-TAUTOLOGICAL-TESTS.md new file mode 100644 index 0000000..c26905f --- /dev/null +++ b/src/guidelines/ai/M-TAUTOLOGICAL-TESTS.md @@ -0,0 +1,21 @@ + + +## Tests do not assert ground truth (M-TAUTOLOGICAL-TESTS) { #M-TAUTOLOGICAL-TESTS } + +to avoid adding noise without value. +0.1 + +Unit tests should verify meaningful behavior instead of repeating foundational definitions. + +Agents frequently produce tests that re-state the expected value from the same logic the code under test uses, or that simply mirror the implementation's branches. Such tests pass by construction, provide virtually no value, but increase the noise floor of subsequent changes: + +```rust +const CHECKPOINTS: [u32; 4] = [0, 90, 180, 270]; + +#[test] +fn checkpoints_are_correct() { + assert_eq!(CHECKPOINTS, [0, 90, 180, 270]); +} +``` + +Instead, a meaningful test would check a property the constants are supposed to satisfy, for example that they are evenly spaced, monotonically increasing, or impose some direction in related logic. diff --git a/src/guidelines/ai/README.md b/src/guidelines/ai/README.md index bd01803..13727d3 100644 --- a/src/guidelines/ai/README.md +++ b/src/guidelines/ai/README.md @@ -3,3 +3,8 @@ # AI Guidelines {{#include M-DESIGN-FOR-AI.md}} +{{#include M-HUMAN-REVIEW.md}} +{{#include M-SINGLE-ITEM-PATH.md}} +{{#include M-NO-META-DESIGN-DOCUMENTATION.md}} +{{#include M-TAUTOLOGICAL-TESTS.md}} +{{#include M-RUST-SHAPED.md}} diff --git a/src/guidelines/apps/M-TARGET-CPU.md b/src/guidelines/apps/M-TARGET-CPU.md new file mode 100644 index 0000000..0f462b1 --- /dev/null +++ b/src/guidelines/apps/M-TARGET-CPU.md @@ -0,0 +1,17 @@ + + +## Applications target highest viable target-cpu (M-TARGET-CPU) { #M-TARGET-CPU } + +to improve fleet performance. +0.1 + +Server applications should compile against the highest `target-cpu` that the deployment environment is guaranteed to support, rather than defaulting to the generic baseline. + +This can be achieved by setting inside `.cargo/config.toml` for example + +```toml +[target.x86_64-unknown-linux-gnu] +rustflags = ["-C", "target-cpu=x86-64-v3"] +``` + +Note this guideline applies only to applications, as target settings are ignored for libraries. diff --git a/src/guidelines/apps/README.md b/src/guidelines/apps/README.md index 9ce4990..0d57752 100644 --- a/src/guidelines/apps/README.md +++ b/src/guidelines/apps/README.md @@ -4,3 +4,4 @@ {{#include M-MIMALLOC-APPS.md}} {{#include M-APP-ERROR.md}} +{{#include M-TARGET-CPU.md}} diff --git a/src/guidelines/checklist/README.md b/src/guidelines/checklist/README.md index f51cd58..b4f5f6d 100644 --- a/src/guidelines/checklist/README.md +++ b/src/guidelines/checklist/README.md @@ -9,43 +9,70 @@ - [ ] Public types are Debug ([M-PUBLIC-DEBUG]) - [ ] Public types meant to be read are Display ([M-PUBLIC-DISPLAY]) - [ ] If in doubt, split the crate ([M-SMALLER-CRATES]) - - [ ] Names are free of weasel words ([M-CONCISE-NAMES]) + - [ ] Names are free of weasel words ([M-WEASEL-WORDS]) + - [ ] Names of items are generally short ([M-SHORT-NAMES]) - [ ] Prefer regular over associated functions ([M-REGULAR-FN]) - [ ] Panic means 'stop the program' ([M-PANIC-IS-STOP]) - [ ] Detected programming bugs are panics, not errors ([M-PANIC-ON-BUG]) - [ ] Magic values are documented ([M-DOCUMENTED-MAGIC]) - [ ] Use structured logging with message templates ([M-LOG-STRUCTURED]) + - [ ] Production code uses telemetry, not println ([M-LOG-NOT-PRINT]) - **Library / Interoperability** - [ ] Types are Send ([M-TYPES-SEND]) - [ ] Native escape hatches ([M-ESCAPE-HATCHES]) - [ ] Don't leak external types ([M-DONT-LEAK-TYPES]) + - [ ] Items come from their original crate ([M-FOREIGN-REEXPORTS]) - **Library / UX** - [ ] Abstractions don't visibly nest ([M-SIMPLE-ABSTRACTIONS]) - [ ] Avoid smart pointers and wrappers in APIs ([M-AVOID-WRAPPERS]) - [ ] Prefer types over generics, generics over dyn traits ([M-DI-HIERARCHY]) - [ ] Errors are canonical structs ([M-ERRORS-CANONICAL-STRUCTS]) + - [ ] Canonical error conversion uses `From`, not `map_err` ([M-FROM-ERROR]) - [ ] Complex type construction has builders ([M-INIT-BUILDER]) + - [ ] Builders validate in final `.build()` ([M-BUILD-RESULT]) - [ ] Complex type initialization hierarchies are cascaded ([M-INIT-CASCADED]) - [ ] Services are Clone ([M-SERVICES-CLONE]) - [ ] Accept `impl AsRef<>` where feasible ([M-IMPL-ASREF]) - [ ] Accept `impl RangeBounds<>` where feasible ([M-IMPL-RANGEBOUNDS]) - [ ] Accept `impl 'IO'` where feasible ('sans IO') ([M-IMPL-IO]) - [ ] Essential functionality should be inherent ([M-ESSENTIAL-FN-INHERENT]) + - [ ] Extension traits are reserved for foreign items ([M-EXT-TRAITS-FOREIGN-ITEMS]) + - [ ] Modules are balanced in size and scope ([M-BALANCED-MODULES]) + - [ ] Don't define preludes ([M-NO-PRELUDE]) + - [ ] Parameter ordering is consistent across crates or ecosystem ([M-PARAMETER-CONSISTENCY]) + - [ ] Important parameters go first, closures last ([M-PARAMETER-ORDER]) + - [ ] Collections implement the appropriate iter traits ([M-COLLECTION-TRAITS]) + - [ ] Where possible functions are `async` over returning a Future ([M-ASYNC-FN]) - **Library / Resilience** - [ ] I/O and system calls are mockable ([M-MOCKABLE-SYSCALLS]) - [ ] Test utilities are feature gated ([M-TEST-UTIL]) + - [ ] Integration tests live under `tests/` ([M-INTEGRATION-TESTS]) - [ ] Use the proper type family ([M-STRONG-TYPES]) + - [ ] Newtypes guard their invariants ([M-STRONG-TYPES-GUARD]) - [ ] Don't glob re-export items ([M-NO-GLOB-REEXPORTS]) - [ ] Avoid statics ([M-AVOID-STATICS]) + - [ ] Panic continuation is last resort ([M-PANIC-CONTINUATION]) + - [ ] Custom panics have a helpful message ([M-PANIC-MESSAGE]) - **Library / Building** - [ ] Libraries work out of the box ([M-OOBE]) - [ ] Native `-sys` crates compile without dependencies ([M-SYS-CRATES]) - [ ] Features are additive ([M-FEATURES-ADDITIVE]) +- **Macros** + - [ ] Macros are a last resort ([M-MACRO-LAST-RESORT]) + - [ ] Prefer 'macros by example' over proc macros ([M-MBE-OVER-PROC]) + - [ ] Macros don't lie about signatures ([M-MACROS-DONT-LIE]) + - [ ] Macros assume main crate ([M-MACRO-MAIN-CRATE]) + - [ ] Third party items come from hidden `_private` module ([M-MACRO-HELPERS]) + - [ ] Proc macros should have separate impl crate incl. tests ([M-PROC-IMPL]) + - [ ] Proc macros don't produce implied or hidden items ([M-PROC-IMPLIED-ITEMS]) - **Applications** - [ ] Use mimalloc for apps ([M-MIMALLOC-APP]) - [ ] Applications may use Anyhow or derivatives ([M-APP-ERROR]) + - [ ] Applications target highest viable target-cpu ([M-TARGET-CPU]) - **FFI** - [ ] Isolate DLL state between FFI libraries ([M-ISOLATE-DLL-STATE]) + - [ ] Business logic belongs in core crates, FFI only translates ([M-FFI-TRANSLATES]) + - [ ] FFI crates follow established naming conventions ([M-FFI-NAMING]) - **Safety** - [ ] Unsafe needs reason, should be avoided ([M-UNSAFE]) - [ ] Unsafe implies undefined behavior ([M-UNSAFE-IMPLIES-UB]) @@ -54,6 +81,19 @@ - [ ] Optimize for throughput, avoid empty cycles ([M-THROUGHPUT]) - [ ] Identify, profile, optimize the hot path early ([M-HOTPATH]) - [ ] Long-running tasks should have yield points ([M-YIELD-POINTS]) + - [ ] Reuse allocations where possible ([M-MEM-REUSE]) + - [ ] Library telemetry does not tank performance ([M-LOG-OVERHEAD]) + - [ ] Nested type hierarchies should avoid needless indirection ([M-AVOID-INDIRECTION]) + - [ ] Use boxed slices and strings for immutable owned sequences ([M-BOX-DST]) + - [ ] Shrink collections to fit after building ([M-SHRINK-TO-FIT]) + - [ ] Use a fast hasher where possible ([M-FAST-HASHER]) + - [ ] Collections are created with sufficient initial capacity ([M-INITIAL-CAPACITY]) +- **Project** + - [ ] Common settings come from the workspace Cargo.toml ([M-CARGO-WORKSPACE]) + - [ ] The workspace lists and versions all crates ([M-CRATES-IN-WORKSPACE]) + - [ ] All crates are siblings in one folder ([M-CRATES-FLAT-FOLDER]) + - [ ] New crates target latest edition ([M-LATEST-EDITION]) + - [ ] MSRV is conservatively updated ([M-MSRV]) - **Documentation** - [ ] First sentence is one line; approx. 15 words ([M-FIRST-DOC-SENTENCE]) - [ ] Has comprehensive module documentation ([M-MODULE-DOCS]) @@ -61,6 +101,11 @@ - [ ] Mark `pub use` items with `#[doc(inline)]` ([M-DOC-INLINE]) - **AI** - [ ] Design with AI use in mind ([M-DESIGN-FOR-AI]) + - [ ] AI-generated code requires human review ([M-HUMAN-REVIEW]) + - [ ] Items are only visible through one path ([M-SINGLE-ITEM-PATH]) + - [ ] Avoid meta design documentation ([M-NO-META-DESIGN-DOCUMENTATION]) + - [ ] Tests should not assert ground truth ([M-TAUTOLOGICAL-TESTS]) + - [ ] Rust code solves Rust problems ([M-RUST-SHAPED]) [M-UPSTREAM-GUIDELINES]: ../universal/#M-UPSTREAM-GUIDELINES @@ -69,18 +114,24 @@ [M-PUBLIC-DEBUG]: ../universal/#M-PUBLIC-DEBUG [M-PUBLIC-DISPLAY]: ../universal/#M-PUBLIC-DISPLAY [M-SMALLER-CRATES]: ../universal/#M-SMALLER-CRATES -[M-CONCISE-NAMES]: ../universal/#M-CONCISE-NAMES +[M-WEASEL-WORDS]: ../universal/#M-WEASEL-WORDS +[M-SHORT-NAMES]: ../universal/#M-SHORT-NAMES [M-REGULAR-FN]: ../universal/#M-REGULAR-FN [M-PANIC-IS-STOP]: ../universal/#M-PANIC-IS-STOP [M-PANIC-ON-BUG]: ../universal/#M-PANIC-ON-BUG +[M-PANIC-CONTINUATION]: ../libs/resilience/#M-PANIC-CONTINUATION +[M-PANIC-MESSAGE]: ../libs/resilience/#M-PANIC-MESSAGE [M-DOCUMENTED-MAGIC]: ../universal/#M-DOCUMENTED-MAGIC [M-LOG-STRUCTURED]: ../universal/#M-LOG-STRUCTURED +[M-LOG-NOT-PRINT]: ../universal/#M-LOG-NOT-PRINT [M-TYPES-SEND]: ../libs/interop/#M-TYPES-SEND [M-DONT-LEAK-TYPES]: ../libs/interop/#M-DONT-LEAK-TYPES +[M-FOREIGN-REEXPORTS]: ../libs/interop/#M-FOREIGN-REEXPORTS [M-ESCAPE-HATCHES]: ../libs/interop/#M-ESCAPE-HATCHES [M-STRONG-TYPES]: ../libs/resilience/#M-STRONG-TYPES +[M-STRONG-TYPES-GUARD]: ../libs/resilience/#M-STRONG-TYPES-GUARD [M-NO-GLOB-REEXPORTS]: ../libs/resilience/#M-NO-GLOB-REEXPORTS [M-ESSENTIAL-FN-INHERENT]: ../libs/ux/#M-ESSENTIAL-FN-INHERENT [M-MOCKABLE-SYSCALLS]: ../libs/resilience/#M-MOCKABLE-SYSCALLS @@ -88,13 +139,23 @@ [M-AVOID-WRAPPERS]: ../libs/ux/#M-AVOID-WRAPPERS [M-DI-HIERARCHY]: ../libs/ux/#M-DI-HIERARCHY [M-ERRORS-CANONICAL-STRUCTS]: ../libs/ux/#M-ERRORS-CANONICAL-STRUCTS +[M-FROM-ERROR]: ../libs/ux/#M-FROM-ERROR [M-INIT-BUILDER]: ../libs/ux/#M-INIT-BUILDER +[M-BUILD-RESULT]: ../libs/ux/#M-BUILD-RESULT [M-INIT-CASCADED]: ../libs/ux/#M-INIT-CASCADED [M-SERVICES-CLONE]: ../libs/ux/#M-SERVICES-CLONE [M-IMPL-ASREF]: ../libs/ux/#M-IMPL-ASREF [M-IMPL-RANGEBOUNDS]: ../libs/ux/#M-IMPL-RANGEBOUNDS [M-IMPL-IO]: ../libs/ux/#M-IMPL-IO +[M-BALANCED-MODULES]: ../libs/ux/#M-BALANCED-MODULES +[M-NO-PRELUDE]: ../libs/ux/#M-NO-PRELUDE +[M-PARAMETER-CONSISTENCY]: ../libs/ux/#M-PARAMETER-CONSISTENCY +[M-PARAMETER-ORDER]: ../libs/ux/#M-PARAMETER-ORDER +[M-COLLECTION-TRAITS]: ../libs/ux/#M-COLLECTION-TRAITS +[M-ASYNC-FN]: ../libs/ux/#M-ASYNC-FN +[M-EXT-TRAITS-FOREIGN-ITEMS]: ../libs/ux/#M-EXT-TRAITS-FOREIGN-ITEMS [M-TEST-UTIL]: ../libs/resilience/#M-TEST-UTIL +[M-INTEGRATION-TESTS]: ../libs/resilience/#M-INTEGRATION-TESTS [M-AVOID-STATICS]: ../libs/resilience/#M-AVOID-STATICS [M-OOBE]: ../libs/building/#M-OOBE [M-SYS-CRATES]: ../libs/resilience/#M-SYS-CRATES @@ -103,9 +164,12 @@ [M-APP-ERROR]: ../apps/#M-APP-ERROR [M-MIMALLOC-APP]: ../apps/#M-MIMALLOC-APP +[M-TARGET-CPU]: ../apps/#M-TARGET-CPU [M-ISOLATE-DLL-STATE]: ../ffi/#M-ISOLATE-DLL-STATE +[M-FFI-TRANSLATES]: ../ffi/#M-FFI-TRANSLATES +[M-FFI-NAMING]: ../ffi/#M-FFI-NAMING [M-UNSAFE]: ../safety/#M-UNSAFE @@ -116,6 +180,20 @@ [M-HOTPATH]: ../performance/#M-HOTPATH [M-THROUGHPUT]: ../performance/#M-THROUGHPUT [M-YIELD-POINTS]: ../performance/#M-YIELD-POINTS +[M-MEM-REUSE]: ../performance/#M-MEM-REUSE +[M-LOG-OVERHEAD]: ../performance/#M-LOG-OVERHEAD +[M-AVOID-INDIRECTION]: ../performance/#M-AVOID-INDIRECTION +[M-BOX-DST]: ../performance/#M-BOX-DST +[M-SHRINK-TO-FIT]: ../performance/#M-SHRINK-TO-FIT +[M-FAST-HASHER]: ../performance/#M-FAST-HASHER +[M-INITIAL-CAPACITY]: ../performance/#M-INITIAL-CAPACITY + + +[M-CARGO-WORKSPACE]: ../project/#M-CARGO-WORKSPACE +[M-CRATES-IN-WORKSPACE]: ../project/#M-CRATES-IN-WORKSPACE +[M-CRATES-FLAT-FOLDER]: ../project/#M-CRATES-FLAT-FOLDER +[M-LATEST-EDITION]: ../project/#M-LATEST-EDITION +[M-MSRV]: ../project/#M-MSRV [M-FIRST-DOC-SENTENCE]: ../docs/#M-FIRST-DOC-SENTENCE @@ -123,5 +201,20 @@ [M-CANONICAL-DOCS]: ../docs/#M-CANONICAL-DOCS [M-DOC-INLINE]: ../docs/#M-DOC-INLINE + +[M-MACRO-LAST-RESORT]: ../macros/#M-MACRO-LAST-RESORT +[M-MBE-OVER-PROC]: ../macros/#M-MBE-OVER-PROC +[M-MACROS-DONT-LIE]: ../macros/#M-MACROS-DONT-LIE +[M-MACRO-MAIN-CRATE]: ../macros/#M-MACRO-MAIN-CRATE +[M-MACROS-USE-MAIN-CRATE]: ../macros/#M-MACROS-USE-MAIN-CRATE +[M-MACRO-HELPERS]: ../macros/#M-MACRO-HELPERS +[M-PROC-IMPL]: ../macros/#M-PROC-IMPL +[M-PROC-IMPLIED-ITEMS]: ../macros/#M-PROC-IMPLIED-ITEMS + [M-DESIGN-FOR-AI]: ../ai/#M-DESIGN-FOR-AI +[M-HUMAN-REVIEW]: ../ai/#M-HUMAN-REVIEW +[M-SINGLE-ITEM-PATH]: ../ai/#M-SINGLE-ITEM-PATH +[M-NO-META-DESIGN-DOCUMENTATION]: ../ai/#M-NO-META-DESIGN-DOCUMENTATION +[M-TAUTOLOGICAL-TESTS]: ../ai/#M-TAUTOLOGICAL-TESTS +[M-RUST-SHAPED]: ../ai/#M-RUST-SHAPED diff --git a/src/guidelines/ffi/M-FFI-NAMING.md b/src/guidelines/ffi/M-FFI-NAMING.md new file mode 100644 index 0000000..53d1ff0 --- /dev/null +++ b/src/guidelines/ffi/M-FFI-NAMING.md @@ -0,0 +1,13 @@ + + +## FFI crates follow established naming conventions (M-FFI-NAMING) { #M-FFI-NAMING } + +to make the role crates immediately recognizable across projects. +0.1 + +Crates used for FFI should follow established naming practices: + +- `-sys` for crates defining items to call into existing (C-style) libraries +- `-ffi` for crates defining (C-style) items when called from existing applications + +There are slight variations of this scheme (e.g., `-sys2` when a previous `-sys` crate was abandoned and using `-` vs `_`), but overall one clearly defines 'export' libraries, the other one 'import' ones. diff --git a/src/guidelines/ffi/M-FFI-TRANSLATES.md b/src/guidelines/ffi/M-FFI-TRANSLATES.md new file mode 100644 index 0000000..f039182 --- /dev/null +++ b/src/guidelines/ffi/M-FFI-TRANSLATES.md @@ -0,0 +1,51 @@ + + +## Business logic belongs in core crates, FFI only translates (M-FFI-TRANSLATES) { #M-FFI-TRANSLATES } + +to maximize safe code and have clean separation of concerns. +0.1 + +When Rust is used to create FFI libraries, there should be a clear separation of concerns between the core _business logic_ crate `foo` and the glue crate `foo-ffi`. + +Any operational functionality belongs in the core crate and should be expressed as idiomatic, safe, testable Rust. The FFI crate exists only to translate between native Rust and C constructs, and the core crate must not be infected with interop concerns, even if this means repeating, and slightly adjusting, type and function signatures. For example, given the following type in the core crate `foo`: + +```rust +pub struct Message { + destination: [u8; 8], + data: Vec, +} + +impl Message { + pub fn new(destination: [u8; 8], data: Vec) -> Self { /* ... */ } + pub fn transmit(&self) -> Result<(), TransmitError> { /* ... */ } +} +``` + +A proper separation of concerns might collapse construction and transmission into a single FFI entry point in `foo-ffi`: + +```rust +#[no_mangle] +pub unsafe extern "C" fn transmit_message( + destination: *const [u8; 8], + data: *const u8, + data_len: usize, +) -> u8 { + let data = std::slice::from_raw_parts(data, data_len).to_vec(); + match Message::new(*destination, data).transmit() { + Ok(()) => 0, + Err(_) => 1, + } +} +``` + +However, it would be improper to leak FFI requirements into `foo` itself: ownership, data models and signatures do not translate seamlessly between the two worlds. Any time _saved_ by skipping a clean split will have to be paid back many times over during refactorings down the line. + +```rust +#[repr(C)] +pub struct Message { + pub destination: [u8; 8], + pub data_ptr: *mut u8, + pub data_len: usize, + pub data_cap: usize, +} +``` diff --git a/src/guidelines/ffi/README.md b/src/guidelines/ffi/README.md index f3a6c30..35b41a8 100644 --- a/src/guidelines/ffi/README.md +++ b/src/guidelines/ffi/README.md @@ -3,3 +3,5 @@ # FFI Guidelines {{#include M-ISOLATE-DLL-STATE.md}} +{{#include M-FFI-TRANSLATES.md}} +{{#include M-FFI-NAMING.md}} diff --git a/src/guidelines/libs/interop/M-FOREIGN-REEXPORTS.md b/src/guidelines/libs/interop/M-FOREIGN-REEXPORTS.md new file mode 100644 index 0000000..86676cd --- /dev/null +++ b/src/guidelines/libs/interop/M-FOREIGN-REEXPORTS.md @@ -0,0 +1,14 @@ + + +## Items come from their original crate (M-FOREIGN-REEXPORTS) { #M-FOREIGN-REEXPORTS } + +to avoid type confusion. +0.1 + +Crates should generally not re-export items from other crates. For example, if your crate contains a method `foo::download(url: bar::Url)`, you should not do `pub use bar::Url` from inside `foo`. This avoids having possibly dozens of aliases in context, which can get confusing for both users and agents, in particular if these are mixed with genuinely different types of the same name from other crates. + +When a crate accepts or returns a type defined in some third-party crate, users are be expected to depend on that third-party crate directly and import the type from there. That said, there are a few valid exceptions to this rule: + +- Umbrella crates (compare M-DONT-LEAK-TYPES) by definition re-export other types +- Crates split for technical reasons (e.g., exporting `foo_core::Url` from `foo`) +- Macro use to provide stable paths, e.g., via some hidden `foo::__private::Url` diff --git a/src/guidelines/libs/interop/README.md b/src/guidelines/libs/interop/README.md index 8c37c7d..dda5474 100644 --- a/src/guidelines/libs/interop/README.md +++ b/src/guidelines/libs/interop/README.md @@ -5,3 +5,4 @@ {{#include M-TYPES-SEND.md}} {{#include M-ESCAPE-HATCHES.md}} {{#include M-DONT-LEAK-TYPES.md}} +{{#include M-FOREIGN-REEXPORTS.md}} diff --git a/src/guidelines/libs/resilience/M-INTEGRATION-TESTS.md b/src/guidelines/libs/resilience/M-INTEGRATION-TESTS.md new file mode 100644 index 0000000..8aa2d2d --- /dev/null +++ b/src/guidelines/libs/resilience/M-INTEGRATION-TESTS.md @@ -0,0 +1,10 @@ + + +## Integration tests live under `tests/` (M-INTEGRATION-TESTS) { #M-INTEGRATION-TESTS } + +To keep code files reasonably clean. +0.1 + +Tests that only touch public API surface are _integration tests_ and belong under `tests/`, not `mod tests {}`. + +In projects with coverage targets, it is not uncommon for `src/` files to contain more testing code than actual business logic. This can make browsing and understanding the code harder both in IDEs and PRs. Likewise, if a testing goal can be achieved through either an integration test or a unit test, the former is always preferred. Shared helpers between integration tests should live in a subdirectory module, e.g. `tests/common/mod.rs`. diff --git a/src/guidelines/libs/resilience/M-PANIC-CONTINUATION.md b/src/guidelines/libs/resilience/M-PANIC-CONTINUATION.md new file mode 100644 index 0000000..396dc65 --- /dev/null +++ b/src/guidelines/libs/resilience/M-PANIC-CONTINUATION.md @@ -0,0 +1,34 @@ + + +## Panic continuation is last resort (M-PANIC-CONTINUATION) { #M-PANIC-CONTINUATION } + +to avoid subtle bugs and state corruption. +0.1 + +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 and 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: + +```rust +thread_local! { + static ALWAYS_EQUAL: RefCell<(i32, i32)> = RefCell::new((0, 0)); +} + +fn main() { + let _ = panic::catch_unwind(|| { + ALWAYS_EQUAL.with_borrow_mut(|p| { + p.0 += 1; + panic!("Assume some user-provided closure failed here"); + p.1 += 1; + }); + }); + + ALWAYS_EQUAL.with_borrow(|p| { + assert_eq!(p.0, p.1); // Broken! + }); +} +``` + +Although the example above is slightly contrived, the side effects and interactions of a caught panic can harder to identify, can have wider blast radius, and be subtle. + +Systems where many unrelated tasks are in flight (e.g., server request handler) can use `catch_unwind` on a per-request basis, but should still promote an application restart after a request handler caused a panic. The purpose of `catch_unwind` here is not to continue execution indefinitely, but to allow all other requests to gracefully finish. diff --git a/src/guidelines/libs/resilience/M-PANIC-MESSAGE.md b/src/guidelines/libs/resilience/M-PANIC-MESSAGE.md new file mode 100644 index 0000000..cb3efe4 --- /dev/null +++ b/src/guidelines/libs/resilience/M-PANIC-MESSAGE.md @@ -0,0 +1,16 @@ + + +## Custom panics have a helpful message (M-PANIC-MESSAGE) { #M-PANIC-MESSAGE } + +to lower the time it takes to understand bugs. +0.1 + +When code panics intentionally (via `panic!`, `assert!`, `unreachable!`, `todo!`, or similar), a message must be present to clearly state what went wrong and, where applicable, include relevant values. + +```rust +// Bad, the panic gives the developer little to act on. +assert!(buffer.len() >= HEADER_SIZE); + +// Good, message contains reason and actual values. +assert!(buffer.len() >= HEADER_SIZE, "buffer too small for header: got {} bytes, need {HEADER_SIZE}", buffer.len()); +``` diff --git a/src/guidelines/libs/resilience/M-STRONG-TYPES-GUARD.md b/src/guidelines/libs/resilience/M-STRONG-TYPES-GUARD.md new file mode 100644 index 0000000..2bf353c --- /dev/null +++ b/src/guidelines/libs/resilience/M-STRONG-TYPES-GUARD.md @@ -0,0 +1,36 @@ + + +## Newtypes guard their invariants (M-STRONG-TYPES-GUARD) { #M-STRONG-TYPES-GUARD } + +To centralize essential correctness invariants. +0.1 + +When introducing a strong type or newtype that exists to encode an invariant (a non-empty string, a percentage, a port number, a sanitized path, ...) the type itself must enforce that invariant where applicable. + +Construction should be fallible, returning a proper error when the invariant cannot be upheld, rather than handing the responsibility off to every user: + +```rust +// Bad, creates a new type but enforces nothing. Every caller now has to +// re-check that the value is actually a valid month, defeating the point of +// having a dedicated type. +pub struct Month(pub u8); + +impl Month { + pub fn new(value: u8) -> Self { ... } +} + + +// Good, the invariant (1..=12) is checked once, at the boundary, and +// every later use of `Month` can rely on it. +pub struct Month(u8); + +impl Month { + pub fn from_u8(value: u8) -> Result { ... } +} +``` + +This means for any newtype that is non-total: +- It must have at least one fallible constructor (e.g., `fn from_foo(...) -> Result`). +- Additional panicking constructors are allowed (e.g., `new`), but should preferably be `const`. +- Conversions from weaker types into the newtype must be fallible (`TryFrom`/`FromStr`). +- Infallible `From` implementations may not be offered. diff --git a/src/guidelines/libs/resilience/README.md b/src/guidelines/libs/resilience/README.md index f76cbd2..5ce480d 100644 --- a/src/guidelines/libs/resilience/README.md +++ b/src/guidelines/libs/resilience/README.md @@ -4,6 +4,10 @@ {{#include M-MOCKABLE-SYSCALLS.md}} {{#include M-TEST-UTIL.md}} +{{#include M-INTEGRATION-TESTS.md}} {{#include M-STRONG-TYPES.md}} +{{#include M-STRONG-TYPES-GUARD.md}} {{#include M-NO-GLOB-REEXPORTS.md}} {{#include M-AVOID-STATICS.md}} +{{#include M-PANIC-CONTINUATION.md}} +{{#include M-PANIC-MESSAGE.md}} diff --git a/src/guidelines/libs/ux/M-ASYNC-FN.md b/src/guidelines/libs/ux/M-ASYNC-FN.md new file mode 100644 index 0000000..b6b4872 --- /dev/null +++ b/src/guidelines/libs/ux/M-ASYNC-FN.md @@ -0,0 +1,14 @@ + + +## Where possible functions are `async` over returning a Future (M-ASYNC-FN) { #M-ASYNC-FN } + +An `async fn` signature is shorter, infers lifetimes correctly by default, and reads as ordinary control flow; hand-written `-> impl Future` returns add noise, frequently require explicit `+ '_` / `+ Send` bounds, and are easier to get subtly wrong. +0.1 + +Prefer writing `async fn foo(...) -> T` over `fn foo(...) -> impl Future` (or a boxed future) when both are viable. Fall back to an explicit `Future`-returning signature only when the function genuinely cannot be `async` — for example, when extra `Send`/`Sync`/`'static` bounds, manual lifetime control, or returning a stored/boxed future is required. + +- TODO: Enumerate the legitimate reasons to write a non-`async` future-returning signature (e.g., trait methods pre-`async fn in trait` stabilization, manually pinned futures, explicit `Send` bounds on the returned future, returning a `BoxFuture` for object safety). +- TODO: Clarify the rule for trait methods (use `async fn in trait` where available; document any MSRV constraints). +- TODO: Provide a concrete bad example (`fn load(&self) -> impl Future> + '_ { async move { ... } }`). +- TODO: Provide a concrete good example (`async fn load(&self) -> Result { ... }`). +- TODO: Note interaction with M-IMPL-IO, M-SERVICES-CLONE, and any project-wide `Send`-bound conventions. diff --git a/src/guidelines/libs/ux/M-BALANCED-MODULES.md b/src/guidelines/libs/ux/M-BALANCED-MODULES.md new file mode 100644 index 0000000..02404cf --- /dev/null +++ b/src/guidelines/libs/ux/M-BALANCED-MODULES.md @@ -0,0 +1,17 @@ + + +## Modules are balanced in size and scope (M-BALANCED-MODULES) { #M-BALANCED-MODULES } + +To help users understand functionality and API usage. +0.1 + +Your module design should approximately follow established UX practices of menu design: A _reasonable_ number of your most important items should be placed in the crate root, and a comprehensible grouping of the remaining functionality into subordinate modules. + +The two violations of that rule that can be encountered most frequently: flat module roots containing dozens of items without clear ordering, or the excessive use of submodules without items in the crate root. While there are crates where this makes sense (e.g., automatically generated `-sys` crates defining 100s of C items, or umbrella crates like `std` and `tokio`), the majority of library crates are not among them. + +When designing your module layout, consider these factors: + +- Essential items users must find in order to use a crate should go into its root. For example, a `foo_client` crate should probably have its main `Client` struct inside the root. +- Other items should be grouped semantically by use case. Modules named `traits` and `errors` don't help anyone, but `account`, `network` and `status` do. +- Also take into account that modules are the perfect place for module-level documentation that further explains the respective subsystem. + diff --git a/src/guidelines/libs/ux/M-BUILD-RESULT.md b/src/guidelines/libs/ux/M-BUILD-RESULT.md new file mode 100644 index 0000000..7587098 --- /dev/null +++ b/src/guidelines/libs/ux/M-BUILD-RESULT.md @@ -0,0 +1,15 @@ + + +## Builders validate in final `.build()` (M-BUILD-RESULT) { #M-BUILD-RESULT } + +Concentrating validation in the terminal `.build()` call gives users a single, predictable place where invalid configurations are reported, lets individual setter methods stay infallible and chainable, and makes the success type of the builder unambiguous. +0.1 + +A builder's per-field setter methods should accept input without failing. All cross-field validation, required-field checks, and other consistency rules belong in the final `.build()` method, which returns a `Result` (or equivalent) carrying any error. + +- TODO: State the expected `.build()` signature (e.g., `fn build(self) -> Result` vs. infallible `fn build(self) -> T`) and when each is appropriate. +- TODO: Clarify whether setters may ever return `Result` (e.g., for parsing-style inputs) or whether they must always be infallible. +- TODO: Specify how errors should aggregate (single error vs. collected errors for multiple problems). +- TODO: Provide a concrete bad example (a setter that returns `Result`, or validation scattered across setters). +- TODO: Provide a concrete good example (infallible chainable setters; `.build()` returns `Result` with a canonical error type per M-ERRORS-CANONICAL-STRUCTS). +- TODO: Note interaction with M-INIT-BUILDER and M-INIT-CASCADED. diff --git a/src/guidelines/libs/ux/M-COLLECTION-TRAITS.md b/src/guidelines/libs/ux/M-COLLECTION-TRAITS.md new file mode 100644 index 0000000..4bebd7f --- /dev/null +++ b/src/guidelines/libs/ux/M-COLLECTION-TRAITS.md @@ -0,0 +1,16 @@ + + +## Collections implement the appropriate iter traits (M-COLLECTION-TRAITS) { #M-COLLECTION-TRAITS } + +Implementing the standard iterator traits lets custom collections drop into `for` loops, `collect`, and iterator chains the same way `Vec` and `HashMap` do; missing them forces users into ad-hoc workarounds and breaks ecosystem composition. +0.1 + +Custom collection types should implement the iterator-facing traits the standard library uses — at minimum `IntoIterator` for the owned type as well as for `&Collection` and `&mut Collection`, and `FromIterator` / `Extend` where construction or accumulation makes sense. + +- TODO: Enumerate the exact set of required traits (`IntoIterator` on three forms, `FromIterator`, `Extend`) and which are optional vs. recommended. +- TODO: Specify the conventional inherent methods that should accompany them (`iter`, `iter_mut`, `into_iter`, `len`, `is_empty`). +- TODO: Note when *not* to implement a given trait (e.g., `FromIterator` for collections that need extra context to construct). +- TODO: Provide a concrete bad example (a custom collection missing `IntoIterator for &Collection` so users cannot iterate by reference in a `for` loop). +- TODO: Provide a concrete good example. +- TODO: Note interaction with M-ESSENTIAL-FN-INHERENT and M-IMPL-ASREF. + diff --git a/src/guidelines/libs/ux/M-EXT-TRAITS-FOREIGN-ITEMS.md b/src/guidelines/libs/ux/M-EXT-TRAITS-FOREIGN-ITEMS.md new file mode 100644 index 0000000..aa72a78 --- /dev/null +++ b/src/guidelines/libs/ux/M-EXT-TRAITS-FOREIGN-ITEMS.md @@ -0,0 +1,11 @@ + + +## Extension traits are reserved for foreign items (M-EXT-TRAITS-FOREIGN-ITEMS) { #M-EXT-TRAITS-FOREIGN-ITEMS } + +Extension traits add API surface and import friction; they are only justified when inherent methods or owned traits aren't possible because the target type is foreign. +0.1 + +- TODO: Define what counts as an "extension trait" (e.g., a trait whose primary purpose is to add methods to a type owned by another crate via `impl Ext for ForeignType`). +- TODO: Specify when extension traits are acceptable (foreign types from `std` or third-party crates) vs. when they must not be used (types owned by the current crate — use inherent impls or a regular trait instead). +- TODO: Clarify naming, sealing, and visibility expectations for such traits. +- TODO: Provide good/bad examples. diff --git a/src/guidelines/libs/ux/M-FROM-ERROR.md b/src/guidelines/libs/ux/M-FROM-ERROR.md new file mode 100644 index 0000000..e227637 --- /dev/null +++ b/src/guidelines/libs/ux/M-FROM-ERROR.md @@ -0,0 +1,14 @@ + + +## Canonical error conversion uses `From`, not `map_err` (M-FROM-ERROR) { #M-FROM-ERROR } + +When `From` is implemented for the function's error type, the `?` operator converts automatically; sprinkling `.map_err(...)` at call sites duplicates that mapping, hides it from review, and lets variants drift as new conversions are added in different places. +0.1 + +Conversions between error types that are part of the project's canonical error hierarchy should be implemented as `impl From for TargetError` (typically via `#[from]` on a `thiserror`-style derive or an explicit impl) and used implicitly via `?`. Call sites should not reach for `.map_err(...)` to perform the same conversion repeatedly. + +- TODO: Specify when `map_err` is still appropriate (one-off context attachment, lossy summarization, conversions that depend on local context the `From` impl cannot see). +- TODO: Clarify the policy for canonical error structs (cf. M-ERRORS-CANONICAL-STRUCTS) — each source error gets at most one `From` impl per target. +- TODO: Provide a concrete bad example (every call site doing `.map_err(MyError::Io)?` for `std::io::Error`). +- TODO: Provide a concrete good example (`impl From for MyError` once; call sites use `?` directly). +- TODO: Note interaction with M-ERRORS-CANONICAL-STRUCTS and M-APP-ERROR. diff --git a/src/guidelines/libs/ux/M-NO-PRELUDE.md b/src/guidelines/libs/ux/M-NO-PRELUDE.md new file mode 100644 index 0000000..2987dda --- /dev/null +++ b/src/guidelines/libs/ux/M-NO-PRELUDE.md @@ -0,0 +1,30 @@ + + +## Don't define preludes (M-NO-PRELUDE) { #M-NO-PRELUDE } + +To avoid namespace pollution and downstream compilation issues. +0.1 + +Crates must not define a `prelude` or any namespace intended to be imported as `use foo::*`. + +While the Rust Standard Library successfully uses [preludes](https://doc.rust-lang.org/std/prelude/index.html) to define edition items, preludes in crates cause more harm than good. Given today's IDE support they are not needed, and once multiple preludes are used from same crate there is potential for conflicts: + +```rust +use foo::prelude::*; +use bar::prelude::*; +use baz::prelude::*; + +_ = Client::new(); + +// error[E0659]: `Client` is ambiguous +// --> src/lib.rs:17:13 +// | +// 17 | _ = Client; +// | ^^^^^^ ambiguous name +// | +// = note: ambiguous because of multiple glob imports of a name in the same module +``` + +Preludes in particular do not resolve bad module design. If it looks like a prelude would make the crate easier to use or understand, this is almost always an indication that the existing module system needs restructuring, see M-BALANCED-MODULES. + + diff --git a/src/guidelines/libs/ux/M-PARAMETER-CONSISTENCY.md b/src/guidelines/libs/ux/M-PARAMETER-CONSISTENCY.md new file mode 100644 index 0000000..412ff24 --- /dev/null +++ b/src/guidelines/libs/ux/M-PARAMETER-CONSISTENCY.md @@ -0,0 +1,14 @@ + + +## Parameter ordering is consistent across crates or ecosystem (M-PARAMETER-CONSISTENCY) { #M-PARAMETER-CONSISTENCY } + +Consistent parameter order across related APIs reduces cognitive load, prevents argument-swap bugs, and makes it easier to learn and remember a family of functions. +0.1 + +When the same conceptual parameters appear in multiple functions — within a crate or across crates in the same ecosystem — they should appear in the same order everywhere. + +- TODO: Define the precedence when conventions conflict (own crate vs. broader ecosystem vs. `std`). +- TODO: List recurring parameter pairs that need a canonical order (e.g., `src, dst` vs `dst, src`; `key, value`; `haystack, needle`; `expected, actual`). +- TODO: Provide a concrete bad example (two sibling functions with swapped argument order). +- TODO: Provide a concrete good example. +- TODO: Clarify whether this also constrains builder method order, trait method order, or only free/inherent functions. diff --git a/src/guidelines/libs/ux/M-PARAMETER-ORDER.md b/src/guidelines/libs/ux/M-PARAMETER-ORDER.md new file mode 100644 index 0000000..5cf8290 --- /dev/null +++ b/src/guidelines/libs/ux/M-PARAMETER-ORDER.md @@ -0,0 +1,15 @@ + + +## Important parameters go first, closures last (M-PARAMETER-ORDER) { #M-PARAMETER-ORDER } + +A predictable parameter order keeps the most relevant arguments visible at the call site and avoids the awkward formatting that occurs when a long closure precedes plain arguments; following this convention also makes APIs scan-readable across a crate. +0.1 + +Order function parameters from most to least important, and place closures (and other large/inline-defined arguments such as `impl FnMut`, `impl Fn`, builder lambdas) at the end of the signature. + +- TODO: Define "importance" concretely (e.g., the conceptual subject of the operation comes first; configuration knobs follow; optional/contextual data later). +- TODO: Clarify how this interacts with methods that already have a `self` receiver (the receiver is always first; the rule applies to the remaining parameters). +- TODO: Specify the rule for multiple closures (e.g., `map_or_else(default, f)`) — does any closure count as "last", or only single-closure APIs? +- TODO: Provide a concrete bad example (a function taking a closure followed by an integer count). +- TODO: Provide a concrete good example (`fn retry(count: usize, f: impl FnMut() -> Result) -> ...`). +- TODO: Note interaction with M-PARAMETER-CONSISTENCY (which governs cross-crate consistency of the chosen order). diff --git a/src/guidelines/libs/ux/README.md b/src/guidelines/libs/ux/README.md index 7bd860c..02a4acd 100644 --- a/src/guidelines/libs/ux/README.md +++ b/src/guidelines/libs/ux/README.md @@ -6,10 +6,19 @@ {{#include M-AVOID-WRAPPERS.md}} {{#include M-DI-HIERARCHY.md}} {{#include M-ERRORS-CANONICAL-STRUCTS.md}} +{{#include M-FROM-ERROR.md}} {{#include M-INIT-BUILDER.md}} +{{#include M-BUILD-RESULT.md}} {{#include M-INIT-CASCADED.md}} {{#include M-SERVICES-CLONE.md}} {{#include M-IMPL-ASREF.md}} {{#include M-IMPL-RANGEBOUNDS.md}} {{#include M-IMPL-IO.md}} {{#include M-ESSENTIAL-FN-INHERENT.md}} +{{#include M-EXT-TRAITS-FOREIGN-ITEMS.md}} +{{#include M-BALANCED-MODULES.md}} +{{#include M-NO-PRELUDE.md}} +{{#include M-PARAMETER-CONSISTENCY.md}} +{{#include M-PARAMETER-ORDER.md}} +{{#include M-COLLECTION-TRAITS.md}} +{{#include M-ASYNC-FN.md}} diff --git a/src/guidelines/macros/M-MACRO-HELPERS.md b/src/guidelines/macros/M-MACRO-HELPERS.md new file mode 100644 index 0000000..09962e4 --- /dev/null +++ b/src/guidelines/macros/M-MACRO-HELPERS.md @@ -0,0 +1,25 @@ + + +## Third party items come from hidden `_private` module (M-MACRO-HELPERS) { #M-MACRO-HELPERS } + +To prevent surprising compilation errors. +0.1 + +When a macro expansion needs to refer to third-party items, the host crate should re-export those from a hidden module, and the macro should emit fully-qualified paths through that module rather than expecting the user's crate to depend on the third-party crate directly. + +For example, a crate `foo` requiring `bar` traits would do: + +```rust +#[doc(hidden)] +pub mod _private { + pub use ::bar::Bar; +} + +pub use foo_proc::my_macro; +``` + +The `my_macro!` implementation would then rely on its presence in its emitted code: + +```rust +impl ::foo::_private::Bar for MyType { ... } +``` diff --git a/src/guidelines/macros/M-MACRO-LAST-RESORT.md b/src/guidelines/macros/M-MACRO-LAST-RESORT.md new file mode 100644 index 0000000..32f4c94 --- /dev/null +++ b/src/guidelines/macros/M-MACRO-LAST-RESORT.md @@ -0,0 +1,20 @@ + + +## Macros are a last resort (M-MACRO-LAST-RESORT) { #M-MACRO-LAST-RESORT } + +To avoid complexity where it can be avoided. +0.1 + +Macros should only be used if no other viable solution exists, compare this adage: + +> As @littlecalculist always told me, “macros are for when you run out of language”. If you still have language left — and Rust gives you a lot of language — use the language first. +> +> @pcwalton + +Macros are powerful, but come with several downsides, they + +- are magic, and can be impossible to predict what they do, or how they do it, +- disproportionally increase compilation time in projects that otherwise don't rely on them, +- can cause subtle breakage at edition boundaries where Rust syntax and semantics can change. + +Counterintuitively, the more structurally complex the result of a macro expansion is, the worse of an idea it is to use macros for that in the first place. The ideal macro makes your users go "_I know exactly what this will generate, but I don't want to write all of that by hand_". diff --git a/src/guidelines/macros/M-MACRO-MAIN-CRATE.md b/src/guidelines/macros/M-MACRO-MAIN-CRATE.md new file mode 100644 index 0000000..ed5d01d --- /dev/null +++ b/src/guidelines/macros/M-MACRO-MAIN-CRATE.md @@ -0,0 +1,17 @@ + + +## Macros assume main crate (M-MACRO-MAIN-CRATE) { #M-MACRO-MAIN-CRATE } + +To simplify macro logic. +0.1 + +Procedural macros can (and should) assume they are used through their main crate and emit paths for that. + +For crates including proc macros it is common to ship them split in 3 for technical reasons: + +- `foo` - the main crate that re-exports macros from `foo_proc`, along with extra traits or types, +- `foo_proc` - facade re-exporting macros from `foo_proc_impl` with `proc-macro = true`, +- `foo_proc_impl` - the actual macro implementation and unit tests. + +In some cases there can be additional crates involved. Authors might be tempted trying to make both `foo`, `foo_proc`, and siblings work, resulting in complex +re-export hierarchies or the use of 3rd party helpers. In reality, the minimal UX gain is usually not worth added complexity (or compile time overhead), given the ecosystem precedent of mostly not supporting these usage modes in the first place. diff --git a/src/guidelines/macros/M-MACROS-DONT-LIE.md b/src/guidelines/macros/M-MACROS-DONT-LIE.md new file mode 100644 index 0000000..e24632c --- /dev/null +++ b/src/guidelines/macros/M-MACROS-DONT-LIE.md @@ -0,0 +1,26 @@ + + +## Macros don't lie about signatures (M-MACROS-DONT-LIE) { #M-MACROS-DONT-LIE } + +To avoid confusing users and LLMs. +0.1 + +Macros must not (make users) misrepresent signatures or shape of items. + +Macros have the ability to arbitrarily rewrite token streams. They could convert structs to enums, traits to functions, or perform any other transformation imaginable. They should, however, do none of that, as the resulting code will be highly confusing and virtually impossible to predict or reason about. + +Among others, macros must not + +- convert the nature of data types (e.g., structs to enums, ...), +- alter function signatures, +- convert the `async`-ness of items, +- do anything else that materially detaches _what's written_ from _what's happening_. + +```rust +// Bad: Adds extra parameter and marks function `async`. Impossible to +// predict from reading code. +#[magic_transform] +fn foo() { } + +foo(token).await +``` diff --git a/src/guidelines/macros/M-MBE-OVER-PROC.md b/src/guidelines/macros/M-MBE-OVER-PROC.md new file mode 100644 index 0000000..34b4a27 --- /dev/null +++ b/src/guidelines/macros/M-MBE-OVER-PROC.md @@ -0,0 +1,20 @@ + + +## Prefer 'macros by example' over proc macros (M-MBE-OVER-PROC) { #M-MBE-OVER-PROC } + +For easier macro inspection and faster compilation. +0.1 + +When a 'macro by example' can do the job, it should be preferred over proc macros. + +Proc macros are more powerful, but their expansion can't easily be inspected. Where this versatility isn't needed, a simple 'macro by expansion' is the better option. + +```rust +// Bad, attribute macro requires proc macro machinery, can be hard to +// inspect in some IDEs, and isn't needed here. +#[make_new_id] +struct MyId; + +// Good, easier to write, maintain and inspect, faster compilation speed. +make_new_id!(MyId); +``` diff --git a/src/guidelines/macros/M-PROC-HARDCODED-TYPES.md b/src/guidelines/macros/M-PROC-HARDCODED-TYPES.md new file mode 100644 index 0000000..24f4afc --- /dev/null +++ b/src/guidelines/macros/M-PROC-HARDCODED-TYPES.md @@ -0,0 +1,54 @@ + + +## Proc macros don't hardcode types (M-PROC-HARDCODED-TYPES) { #M-PROC-HARDCODED-TYPES } + +To avoid confusing errors, hygiene and visibility issues. +0.1 + +Macros should not define magic types on their own, in particular not public ones, or ones that don't rely on namespace tricks. + +Some macro want to define types, for example + +```rust +#[my_macro] +struct UserType; + +// would expand to + +struct UserType; +struct ExtraType; + +impl UserType { + fn foo() -> ExtraType { ... }; +} +``` + +This is almost always a bad idea for several reasons: + +- they can conflict with existing user-defined types inside the same module, +- if done naively, they can conflict with other expansions of the same macro, +- they can clash with the user's naming conventions, +- they are invisible at source code level and easily forgotten to be re-exported where needed. + +While it is possible for users to work around these limitations somewhat, these are paper cuts your users will have to deal with, possibly months after the fact when refactoring otherwise unrelated code. + +Note that there is one exception to this rule that has generally acceptable UX, the overloaded use of [namespaces](https://doc.rust-lang.org/reference/names/namespaces.html) made prominent by crates like Rocket: + +```rust +#[my_macro] +fn foo() { ... } + +// would expand to + +fn foo() { ... } + +struct foo; +impl SomeTrait for foo { ... } +``` + +Here a new type `foo` is introduced with the same name as the function `foo`. Due to Rust's namespace rules they can co-exit and are automatically re-exported with their parent, and due to [Rust's casing rules (C-CASE)](https://rust-lang.github.io/api-guidelines/naming.html#casing-conforms-to-rfc-430-c-case) these are highly unlikely to clash with user-defined types. However, they would still not make for a pretty _public_ type, and are therefore mainly used inside root crates to define request handlers or FFI functions. + +> ### Namespaces != Modules +> +> Namespaces in Rust have nothing to do with namespaces in other languages. A namespace in C# is approximately a module in Rust. A namespace in Rust +is an esoteric property of names (e.g., `fn foo`, `struct Bar {}`, `moo!`) that decides which 'naming bucket' it lives in inside a module. diff --git a/src/guidelines/macros/M-PROC-IMPL.md b/src/guidelines/macros/M-PROC-IMPL.md new file mode 100644 index 0000000..606f326 --- /dev/null +++ b/src/guidelines/macros/M-PROC-IMPL.md @@ -0,0 +1,30 @@ + + +## Proc macros should have separate impl crate incl. tests (M-PROC-IMPL) { #M-PROC-IMPL } + +To allow for better testing. +0.1 + +Proc macros should be thin shims inside some `foo_proc` crate that delegate to a separate, regular library crate, usually called `foo_proc_impl`, which contains the actual token-stream transformation logic and its tests. + +As proc macro crates are special, testing them from `foo_proc` usually requires workaround for unit and snapshot tests. Instead, consider having a `foo_proc_impl` crate: + +```rust +use proc_macro2::TokenStream; + +pub fn my_macro(attr: TokenStream, item: TokenStream) -> TokenStream { ... } +``` +These can come with regular [insta](https://insta.rs/) or similar snapshot tests, and are then exported as genuine proc macros via a `foo_proc` crate like so: + +```rust +#[proc_macro_attribute] +pub fn my_macro(attr: TokenStream, item: TokenStream) -> TokenStream { + foo_proc_impl::my_macro(attr.into(), item.into()).into() +} +``` +The macros are then re-exported from the core crate: + +```rust +pub use foo_proc::my_macro; +``` +Inside the core crate, we also recommend adding [trybuild](https://docs.rs/trybuild/latest/trybuild/) UI tests with negative examples to ensure consistent error messages. diff --git a/src/guidelines/macros/M-PROC-IMPLIED-ITEMS.md b/src/guidelines/macros/M-PROC-IMPLIED-ITEMS.md new file mode 100644 index 0000000..97b540a --- /dev/null +++ b/src/guidelines/macros/M-PROC-IMPLIED-ITEMS.md @@ -0,0 +1,54 @@ + + +## Proc macros don't produce implied or hidden items (M-PROC-IMPLIED-ITEMS) { #M-PROC-IMPLIED-ITEMS } + +To avoid confusing errors, hygiene and visibility issues. +0.1 + +Macros should not define magic types on their own, in particular not public ones, or ones that don't rely on namespace tricks. + +Some macro want to define types, for example + +```rust +#[my_macro] +struct UserType; + +// would expand to + +struct UserType; +struct ExtraType; + +impl UserType { + fn foo() -> ExtraType { ... }; +} +``` + +This is almost always a bad idea for several reasons: + +- they can conflict with existing user-defined types inside the same module, +- if done naively, they can conflict with other expansions of the same macro, +- they can clash with the user's naming conventions, +- they are invisible at source code level and easily forgotten to be re-exported where needed. + +While it is possible for users to work around these limitations somewhat, these are paper cuts your users will have to deal with, possibly months after the fact when refactoring otherwise unrelated code. + +Note that there is one exception to this rule that has generally acceptable UX, the overloaded use of [namespaces](https://doc.rust-lang.org/reference/names/namespaces.html) made prominent by crates like Rocket: + +```rust +#[my_macro] +fn foo() { ... } + +// would expand to + +fn foo() { ... } + +struct foo; +impl SomeTrait for foo { ... } +``` + +Here a new type `foo` is introduced with the same name as the function `foo`. Due to Rust's namespace rules they can co-exit and are automatically re-exported with their parent, and due to [Rust's casing rules (C-CASE)](https://rust-lang.github.io/api-guidelines/naming.html#casing-conforms-to-rfc-430-c-case) these are highly unlikely to clash with user-defined types. However, they would still not make for a pretty _public_ type, and are therefore mainly used inside root crates to define request handlers or FFI functions. + +> ### Namespaces != Modules +> +> Namespaces in Rust have nothing to do with namespaces in other languages. A namespace in C# is approximately a module in Rust. A namespace in Rust +is an esoteric property of names (e.g., `fn foo`, `struct Bar {}`, `moo!`) that decides which 'naming bucket' it lives in inside a module. diff --git a/src/guidelines/macros/README.md b/src/guidelines/macros/README.md new file mode 100644 index 0000000..e2e9480 --- /dev/null +++ b/src/guidelines/macros/README.md @@ -0,0 +1,11 @@ + + +# Macros Guidelines + +{{#include M-MACRO-LAST-RESORT.md}} +{{#include M-MBE-OVER-PROC.md}} +{{#include M-MACROS-DONT-LIE.md}} +{{#include M-MACRO-MAIN-CRATE.md}} +{{#include M-MACRO-HELPERS.md}} +{{#include M-PROC-IMPL.md}} +{{#include M-PROC-IMPLIED-ITEMS.md}} diff --git a/src/guidelines/performance/M-AVOID-INDIRECTION.md b/src/guidelines/performance/M-AVOID-INDIRECTION.md new file mode 100644 index 0000000..4674d48 --- /dev/null +++ b/src/guidelines/performance/M-AVOID-INDIRECTION.md @@ -0,0 +1,46 @@ + + +## Nested type hierarchies should avoid needless indirection (M-AVOID-INDIRECTION) { #M-AVOID-INDIRECTION } + +To avoid costly stalls waiting for DRAM. +0.1 + +Hot types should avoid nested heap indirection and consider lifting hot, cacheable deep fields to improve cache utilization. + +While the gold standard is to benchmark, a pattern that emerges repeatedly when porting code C# code to Rust is to reflexively `Arc`ing nested types, often multiple layers deep. Although this can make sense on very wide or heavyweight types that genuinely need to be shared by multiple owners, this pattern can ruin access latency when multiple rounds of DRAM lookup have to be performed sequentially. + +Where nested, shared ownership isn't strictly needed, it is usually better to start with local, embedded data, and lifted cacheable fields. + +```rust +// Bad, `print` (assuming it is reasonably hot) needs 2 indirections +// to query whether it is enabled. +struct Item { + config: Arc, + payload: Payload, +} + +struct Config { + feature: Arc +} + +impl Item { + fn print(&self) { + if self.config.feature.is_enabled() { ... } + } +} + +// Better: `enabled` resides nearby and is likely immediately available +// once `print` is called. +struct Item { + config: Arc, + payload: Payload, + enabled: bool, +} + +impl Item { + fn print(&self) { + if self.enabled { ... } + } +} + +``` diff --git a/src/guidelines/performance/M-BOX-DST.md b/src/guidelines/performance/M-BOX-DST.md new file mode 100644 index 0000000..7b739e1 --- /dev/null +++ b/src/guidelines/performance/M-BOX-DST.md @@ -0,0 +1,32 @@ + + +## Use boxed slices and strings for immutable owned sequences (M-BOX-DST) { #M-BOX-DST } + +To reduce memory consumption and better utilize caches. +0.1 + +Frequently used, internal, immutable sequences that will not be resized after construction should be stored as `Box<[T]>`, `Arc` or similar, rather than their original `Vec` 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: + +- 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 + +Some collections provide dedicated methods for this, e.g., `String::into_boxed_str`. + +```rust +// Bad, with many entries this wastes space and makes +// traversal ultimately slower. The internal representation +// won't +struct Data { + ids: Vec +} + +// Good, reduces memory consumption and fits more elements +// into cache. +struct Data { + ids: Vec> +} +``` diff --git a/src/guidelines/performance/M-FAST-HASHER.md b/src/guidelines/performance/M-FAST-HASHER.md new file mode 100644 index 0000000..c58a181 --- /dev/null +++ b/src/guidelines/performance/M-FAST-HASHER.md @@ -0,0 +1,18 @@ + + +## Use a fast hasher where possible (M-FAST-HASHER) { #M-FAST-HASHER } + +to improve performance. +0.1 + +When hashing trusted, internal keys, prefer a fast non-cryptographic hasher (e.g., `FxHash`) over the standard library default. + +Rust's default hasher is reasonably DoS safe on untrusted user input, but this comes at a performance penalty. If you can trust that keys are not maliciously crafted to overflow individual buckets, a custom fast hasher can yield significant performance gains. + +```rust +// Bad, uses default hasher for keys we control. +let lookup = HashMap::::with_capacity(1024); + +// Good, uses faster fxhash for internal keys. +let lookup = HashMap::::with_capacity(1024); +``` diff --git a/src/guidelines/performance/M-INITIAL-CAPACITY.md b/src/guidelines/performance/M-INITIAL-CAPACITY.md new file mode 100644 index 0000000..763fc57 --- /dev/null +++ b/src/guidelines/performance/M-INITIAL-CAPACITY.md @@ -0,0 +1,31 @@ + + +## Collections are created with sufficient initial capacity (M-INITIAL-CAPACITY) { #M-INITIAL-CAPACITY } + +To avoid performance penalties when creating collections. +0.1 + +Where the final or approximate size of a collection (`Vec`, `String`, `HashMap`, `HashSet`, etc.) is known at construction time, it should be created via `with_capacity` rather than `new` or `default`. + +Collections created without capacity may be re-allocated multiple times during their initialization, which also includes copying their content. Creating them with sufficient capacity an entirely avoid this needless overhead. + +```rust +// Bad, probably re-allocates and copies concent over multiple times. +let mut rval = Vec::new(); +for x in &other { + rval.push(convert(x)); +} + +// Better, creates collection with sufficient capacity upfront. +let mut rval = Vec::with_capacity(other.len()); +for x in &other { + rval.push(convert(x)); +} +``` + +Iterator-driven construction (`collect`) inherits this behavior via `size_hint` and should be preferred over manual `push` loops when possible: + +```rust +// Ideal, looks nicer and is performant +let rval: Vec<_> = other.iter().map(convert).collect(); +``` diff --git a/src/guidelines/performance/M-LOG-OVERHEAD.md b/src/guidelines/performance/M-LOG-OVERHEAD.md new file mode 100644 index 0000000..3257b64 --- /dev/null +++ b/src/guidelines/performance/M-LOG-OVERHEAD.md @@ -0,0 +1,28 @@ + + +## Library telemetry does not tank performance (M-LOG-OVERHEAD) { #M-LOG-OVERHEAD } + +To avoid compounding issues when using telemetry to diagnose problems. +0.1 + +Library code that emits telemetry should ensure that doing so does not meaningfully impact throughput or latency on the hot path. + +Crates offered to 3rd parties emitting logs or metrics should assume telemetry will be permanently enabled, or under load. Care should therefore be taken that the volume and overhead of emitted events is reasonable, and will not cause excessive performance degradation. + +Hot, inner loops should preferably stay free of telemetry emission entirely. If it can't be avoided, the events emitted should be lightweight and avoid allocations (e.g., `format!` string concatenation). + +```rust +// Bad, logs each message and invokes allocation-based formatting. +for m in messages { + log(format!("Emitting message {}", m.id())) +} + +// Better, avoids per-message allocations. +for m in messages { + log(("Emitting message", m.id()) +} + +// Best: If possible, let telemetry users reconstruct what happened offline +log(("Processing message batch", messages.batch_id()) +for m in messages { ... } +``` diff --git a/src/guidelines/performance/M-MEM-REUSE.md b/src/guidelines/performance/M-MEM-REUSE.md new file mode 100644 index 0000000..b6fcc6b --- /dev/null +++ b/src/guidelines/performance/M-MEM-REUSE.md @@ -0,0 +1,48 @@ + + +## Reuse allocations where possible (M-MEM-REUSE) { #M-MEM-REUSE } + +To reduce allocation overhead and improve performance in hot paths. +0.1 + +When designing APIs you should allow users to hold onto reusable resources. Inside your code you should make use of them where available. + +The cost of repeated allocations inside hot loops can be significant, and from a user's perspective they can be invisible unless profiled: + +```rust +// Bad, API design forces new allocation per element. +for id in ids { + let value = db.get(id); +} +``` +While these style of APIs may exist for convenience, they should be auxiliary. Instead, the core APIs should allow users to own the underlying object and re-use it: + +```rust +// Good, allows users to decide whether a new allocation is needed. +let mut value = Value::new(); +for id in ids { + db.get_in(id, &mut value); +} +``` + +The canonical method on reusable types to reuse them is `.clear()`, as can be found on many `std` items. Multiple flavors of this pattern exist. In simple cases user-owned types can hold a preexisting, reusable collection directly: + +```rust +struct Value { + data: Vec +} +``` +In heavyweight, deeply nested libraries it can be worthwhile to either pass a bump-style `Arena`, or to encapsulate one inside the user types, so it can used throughout the call stack: + +```rust +struct Query { + arena: Arena, + request: Request, + data: Vec +} + +fn client_do_work(query: &mut Query) { + let request = rewrite_request(&query.request, &query.arena); + get_in(request, &mut query.data); +} +``` diff --git a/src/guidelines/performance/M-SHRINK-TO-FIT.md b/src/guidelines/performance/M-SHRINK-TO-FIT.md new file mode 100644 index 0000000..8f2aeeb --- /dev/null +++ b/src/guidelines/performance/M-SHRINK-TO-FIT.md @@ -0,0 +1,22 @@ + + +## Shrink collections to fit after building (M-SHRINK-TO-FIT) { #M-SHRINK-TO-FIT } + +To reduce memory footprint. +0.1 + +Where large, long-lived, growable collection such as `Vec`, `String` were built without an exact size reservation (compare M-INITIAL-CAPACITY), the resulting collection should be shrunk via `shrink_to_fit` before storing it. + +Rust's collections grow by powers of two when iteratively adding elements. In the worst case a collection might therefore use ~2x of its needed memory. + +```rust +// Bad, long lived object might end up using 2x needed memory. +let mut long_lived = Vec::new(); +for x in large_iter { + long_lived.push(x); +} + +// Good, frees up extra memory. +long_lived.shrink_to_fit(); +``` +Note, this does not apply to conversions done via `into_boxed_` and friends (compare M-BOX-DST), as these generally shrink before converting already. diff --git a/src/guidelines/performance/README.md b/src/guidelines/performance/README.md index f92e175..201403d 100644 --- a/src/guidelines/performance/README.md +++ b/src/guidelines/performance/README.md @@ -5,3 +5,10 @@ {{#include M-THROUGHPUT.md}} {{#include M-HOTPATH.md}} {{#include M-YIELD-POINTS.md}} +{{#include M-MEM-REUSE.md}} +{{#include M-LOG-OVERHEAD.md}} +{{#include M-AVOID-INDIRECTION.md}} +{{#include M-BOX-DST.md}} +{{#include M-SHRINK-TO-FIT.md}} +{{#include M-FAST-HASHER.md}} +{{#include M-INITIAL-CAPACITY.md}} diff --git a/src/guidelines/project/M-CARGO-WORKSPACE.md b/src/guidelines/project/M-CARGO-WORKSPACE.md new file mode 100644 index 0000000..d270f9a --- /dev/null +++ b/src/guidelines/project/M-CARGO-WORKSPACE.md @@ -0,0 +1,10 @@ + + +## Common settings come from the workspace Cargo.toml (M-CARGO-WORKSPACE) { #M-CARGO-WORKSPACE } + +To ensure consistent, maintainable project configuration. +0.1 + +Any repo with two or more crates that somehow belong together should unify these crates with a workspace `Cargo.toml`. Member 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. diff --git a/src/guidelines/project/M-CRATES-FLAT-FOLDER.md b/src/guidelines/project/M-CRATES-FLAT-FOLDER.md new file mode 100644 index 0000000..141620b --- /dev/null +++ b/src/guidelines/project/M-CRATES-FLAT-FOLDER.md @@ -0,0 +1,10 @@ + + +## All crates are siblings in one folder (M-CRATES-FLAT-FOLDER) { #M-CRATES-FLAT-FOLDER } + +To simplify project navigation and follow established Rust standards. +0.1 + +All crates in a workspace live as direct subdirectories of a single folder (e.g., `crates/`). In rare cases this rule can be broken where two or more aggregation hierarchies exist, such as differentiating unpublished crates from released ones (e.g. `crates/` and `crates_internal/`), or third-party from own (e.g., `vendored/`). + +Placing crates inside other crates (at or below their `Cargo.toml`), or even inside their `src/` folder is never acceptable. If a crate relation should be expressed, this is done via common prefixes instead (e.g., `foo`, `foo_util`, `foo_build`). diff --git a/src/guidelines/project/M-CRATES-IN-WORKSPACE.md b/src/guidelines/project/M-CRATES-IN-WORKSPACE.md new file mode 100644 index 0000000..b33de2b --- /dev/null +++ b/src/guidelines/project/M-CRATES-IN-WORKSPACE.md @@ -0,0 +1,22 @@ + + +## The workspace lists and versions all crates (M-CRATES-IN-WORKSPACE) { #M-CRATES-IN-WORKSPACE } + +To simplify inter-crate dependencies and debugging. +0.1 + +Every crate produced by the project should be listed as a workspace member, and its version should be declared in `[workspace.dependencies]` so that intra-workspace dependencies resolve to a single canonical version. + +```toml +# Bad, crate links its sibling directly +[dependencies] +sibling.path = "../sibling" + + +# Good, going through workspace +[dependencies] +sibling.workspace = true + +[workspace.dependencies] +sibling = { path = "crates/sibling", version = "0.5.2" } +``` diff --git a/src/guidelines/project/M-LATEST-EDITION.md b/src/guidelines/project/M-LATEST-EDITION.md new file mode 100644 index 0000000..262a92c --- /dev/null +++ b/src/guidelines/project/M-LATEST-EDITION.md @@ -0,0 +1,10 @@ + + +## New crates target latest edition (M-LATEST-EDITION) { #M-LATEST-EDITION } + +To get the latest and greatest Rust. +0.1 + +When creating a new crate or workspace, set `edition` to the latest stable edition (at least `2024` at the time of writing); the `resolver` field is generally not needed. + +Using an older edition has generally no upsides for new projects, but forces you to write 'old Rust' that is less idiomatic and has worse UX edge cases. Notably, using an older edition does _not_ grant any compatibility benefits with the rest of the ecosystem. An application based on `2015` can use libraries written for `2024` just fine. diff --git a/src/guidelines/project/M-MSRV.md b/src/guidelines/project/M-MSRV.md new file mode 100644 index 0000000..79d3635 --- /dev/null +++ b/src/guidelines/project/M-MSRV.md @@ -0,0 +1,12 @@ + + +## MSRV is conservatively updated (M-MSRV) { #M-MSRV } + +To enable modern features while maintaining user stability. +0.1 + +A Minimum Supported Rust Version (MSRV) should be set when libraries are first created. It can be updated as new Rust features are needed, but should be kept a few versions behind the most recent compiler release. + +The ecosystem expectation is that projects are compiled with a _reasonably modern_ Rust compiler. + +Bumping MSRV does therefore not require a major release, but can be handled through a minor update (e.g., `1.3` to `1.4`). In fact, any project depending on 3rd party crates is already inherently bound to this contract, thus forcing a major version bump will not confer any benefits, but could possibly bifurcate downstream dependencies. diff --git a/src/guidelines/project/README.md b/src/guidelines/project/README.md new file mode 100644 index 0000000..7d31989 --- /dev/null +++ b/src/guidelines/project/README.md @@ -0,0 +1,9 @@ + + +# Project Guidelines + +{{#include M-CARGO-WORKSPACE.md}} +{{#include M-CRATES-IN-WORKSPACE.md}} +{{#include M-CRATES-FLAT-FOLDER.md}} +{{#include M-LATEST-EDITION.md}} +{{#include M-MSRV.md}} diff --git a/src/guidelines/universal/M-LOG-NOT-PRINT.md b/src/guidelines/universal/M-LOG-NOT-PRINT.md new file mode 100644 index 0000000..60b2e6b --- /dev/null +++ b/src/guidelines/universal/M-LOG-NOT-PRINT.md @@ -0,0 +1,15 @@ + + +## Production code uses telemetry, not println (M-LOG-NOT-PRINT) { #M-LOG-NOT-PRINT } + +`println!` / `eprintln!` / `dbg!` bypass log levels, structured fields, sampling, sinks, and filters; they pollute stdout/stderr in ways that are invisible to telemetry pipelines and uncontrollable in production. +0.1 + +Production code paths should emit diagnostics through the project's telemetry framework (e.g., `tracing`, `log`) rather than via `println!`, `eprintln!`, `print!`, `eprint!`, or `dbg!`. Console output is reserved for CLI binaries that intentionally write to stdout/stderr as their user interface. + +- TODO: Enumerate the legitimate exceptions (CLI binaries' user-facing output, build scripts, examples, tests). +- TODO: Specify the recommended telemetry stack or refer to a separate decision (e.g., `tracing` with structured fields per M-LOG-STRUCTURED). +- TODO: Provide a concrete bad example (a library function calling `eprintln!("failed: {e}")` instead of `tracing::error!`). +- TODO: Provide a concrete good example. +- TODO: Note guidance for `dbg!` — banned in committed code; lint enforcement suggested. +- TODO: Note interaction with M-LOG-STRUCTURED. diff --git a/src/guidelines/universal/M-SHORT-NAMES.md b/src/guidelines/universal/M-SHORT-NAMES.md new file mode 100644 index 0000000..d31f092 --- /dev/null +++ b/src/guidelines/universal/M-SHORT-NAMES.md @@ -0,0 +1,15 @@ + + +## Names of items are short (M-SHORT-NAMES) { #M-SHORT-NAMES } + +Short names read faster, fit on one line at call sites, and discourage smuggling implementation detail or hedge words into identifiers; the surrounding type and module context usually carries the rest of the meaning. +0.1 + +Identifiers for items (functions, methods, types, fields, modules) should stay short, leaning on context — the enclosing module, type, or trait — to disambiguate rather than encoding it into the name itself. + +- TODO: Give a concrete length guideline or heuristic (e.g., prefer one or two words for methods on a type; avoid restating the type name in its methods). +- TODO: Specify when longer names are warranted (rare public free functions where disambiguation is unavoidable, low-level safety-critical APIs). +- TODO: Clarify the relationship to M-WEASEL-WORDS (which targets weasel words) — this rule is about overall length, not specifically filler words. +- TODO: Provide a concrete bad example (`UserService::get_user_by_id_from_database`). +- TODO: Provide a concrete good example (`UserService::get(id)` or `Users::find(id)`). +- TODO: Note interaction with the Rust API Guidelines naming conventions and M-WEASEL-WORDS. diff --git a/src/guidelines/universal/M-CONCISE-NAMES.md b/src/guidelines/universal/M-WEASEL-WORDS.md similarity index 96% rename from src/guidelines/universal/M-CONCISE-NAMES.md rename to src/guidelines/universal/M-WEASEL-WORDS.md index 2c8b211..18bf374 100644 --- a/src/guidelines/universal/M-CONCISE-NAMES.md +++ b/src/guidelines/universal/M-WEASEL-WORDS.md @@ -1,6 +1,6 @@  -## Names are free of weasel words (M-CONCISE-NAMES) { #M-CONCISE-NAMES } +## Names are free of weasel words (M-WEASEL-WORDS) { #M-WEASEL-WORDS } To improve readability. 1.0 diff --git a/src/guidelines/universal/README.md b/src/guidelines/universal/README.md index 3f464a1..8ee9ddc 100644 --- a/src/guidelines/universal/README.md +++ b/src/guidelines/universal/README.md @@ -8,9 +8,11 @@ {{#include M-PUBLIC-DEBUG.md}} {{#include M-PUBLIC-DISPLAY.md}} {{#include M-SMALLER-CRATES.md}} -{{#include M-CONCISE-NAMES.md}} +{{#include M-WEASEL-WORDS.md}} +{{#include M-SHORT-NAMES.md}} {{#include M-REGULAR-FN.md}} {{#include M-PANIC-IS-STOP.md}} {{#include M-PANIC-ON-BUG.md}} {{#include M-DOCUMENTED-MAGIC.md}} {{#include M-LOG-STRUCTURED.md}} +{{#include M-LOG-NOT-PRINT.md}} From 497fcd678699e8d235493d62b8e9dff1d21b8ff6 Mon Sep 17 00:00:00 2001 From: Ralf Biedert Date: Fri, 5 Jun 2026 16:29:49 +0200 Subject: [PATCH 07/10] Cleanup. --- src/guidelines/ai/M-HUMAN-REVIEW.md | 6 +-- src/guidelines/ai/M-RUST-SHAPED.md | 8 +-- src/guidelines/ai/M-SINGLE-ITEM-PATH.md | 6 +-- src/guidelines/apps/M-TARGET-CPU.md | 2 +- src/guidelines/checklist/README.md | 9 ++-- src/guidelines/ffi/M-FFI-NAMING.md | 2 +- src/guidelines/ffi/M-FFI-TRANSLATES.md | 2 +- .../libs/interop/M-FOREIGN-REEXPORTS.md | 2 +- .../libs/resilience/M-INTEGRATION-TESTS.md | 2 +- .../libs/resilience/M-PANIC-CONTINUATION.md | 4 +- .../libs/resilience/M-STRONG-TYPES-GUARD.md | 2 +- src/guidelines/libs/ux/M-BALANCED-MODULES.md | 2 +- src/guidelines/libs/ux/M-NO-PRELUDE.md | 2 +- src/guidelines/macros/M-MACRO-LAST-RESORT.md | 6 +-- src/guidelines/macros/M-MACRO-MAIN-CRATE.md | 3 +- src/guidelines/macros/M-MACROS-DONT-LIE.md | 2 +- src/guidelines/macros/M-MBE-OVER-PROC.md | 2 +- .../macros/M-PROC-HARDCODED-TYPES.md | 54 ------------------- src/guidelines/macros/M-PROC-IMPL.md | 2 +- src/guidelines/macros/M-PROC-IMPLIED-ITEMS.md | 4 +- .../performance/M-AVOID-INDIRECTION.md | 4 +- src/guidelines/performance/M-BOX-DST.md | 11 ++-- .../performance/M-INITIAL-CAPACITY.md | 4 +- src/guidelines/performance/M-LOG-OVERHEAD.md | 4 +- src/guidelines/performance/M-MEM-REUSE.md | 4 +- src/guidelines/performance/M-SHRINK-TO-FIT.md | 4 +- src/guidelines/project/M-CARGO-WORKSPACE.md | 2 +- .../project/M-CRATES-FLAT-FOLDER.md | 4 +- src/guidelines/project/M-LATEST-EDITION.md | 2 +- src/guidelines/project/M-MSRV.md | 2 +- src/guidelines/universal/M-WEASEL-WORDS.md | 6 +-- 31 files changed, 56 insertions(+), 113 deletions(-) delete mode 100644 src/guidelines/macros/M-PROC-HARDCODED-TYPES.md diff --git a/src/guidelines/ai/M-HUMAN-REVIEW.md b/src/guidelines/ai/M-HUMAN-REVIEW.md index 564f731..866b21e 100644 --- a/src/guidelines/ai/M-HUMAN-REVIEW.md +++ b/src/guidelines/ai/M-HUMAN-REVIEW.md @@ -7,13 +7,13 @@ Agents can do a great job authoring APIs within minutes that would take you otherwise hours to complete, but they often do a poor job designing 'for the right thing', or silently drop requirements. -Rust has advantage over many other languages of strong type system to force correctness at compile time, and design APIs that are fast and hard to misuse. Good API design can greatly aid in forcing a correct implementation. +Rust has the advantage over many other languages of a strong type system to force correctness at compile time, and to design APIs that are fast and hard to misuse. Good API design can greatly aid in forcing a correct implementation. However, as APIs also define contracts between you and your users, bad choices can have viral effects (e.g., compare M-AVOID-WRAPPERS, M-AVOID-STATICS) and cannot easily be verified. -Before submiting major PRs or releasing new APIs you and / or other human reviewers must check all guidelines and other requiemetns are adhered to, and the overall API looks reasonable. +Before submitting major PRs or releasing new APIs you and/or other human reviewers must check that all guidelines and other requirements are adhered to, and that the overall API looks reasonable. -In particular ensure all public APIs follows these guidelines and M-UPSTREAM-GUIDELINES. You may use LLMs to point out where these guidelines are not met, but (until model fidelity improves) you cannot take the your agent's word that the guidelines are met. +In particular, ensure all public APIs follow these guidelines and M-UPSTREAM-GUIDELINES. You may use LLMs to point out where these guidelines are not met, but (until model fidelity improves) you cannot take your agent's word that the guidelines are met. diff --git a/src/guidelines/ai/M-RUST-SHAPED.md b/src/guidelines/ai/M-RUST-SHAPED.md index 2b924ed..6662cab 100644 --- a/src/guidelines/ai/M-RUST-SHAPED.md +++ b/src/guidelines/ai/M-RUST-SHAPED.md @@ -7,16 +7,16 @@ When (automatically) porting C#, Java, C++, or similar code to Rust, technical constructs must not be copied 1-on-1. -It is prudent to separate domain aspects from language aspects. Domain aspects address business problems. An algorithm to compute prime numbers or logic how to process a customer table can (and should) work the same when translating between languages. +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 - error handling, -- management of task and threads, +- management of tasks and threads, - component abstractions and their lifetimes, - ownership of parameters, - and many others. -While some language constructs simply don't translate at all (e.g., compared to C#, Rust does not have any meaningful reflection), while others are deceptively similar and might only bite months down the line (e.g., statics, compare M-AVOID-STATICS). +While some language constructs simply don't translate at all (e.g., compared to C#, Rust does not have any meaningful reflection), others are deceptively similar and might only bite months down the line (e.g., statics, compare M-AVOID-STATICS). -As a rule of thumb, structs and their methods can have vaguely similar names, flows, input and outputs, as far as their business functionality is concerned. However, any striking technical similarity between Rust and { C#, Java, Python, ... } implementations is indicative of deeper architectural problems. +As a rule of thumb, structs and their methods can have vaguely similar names, flows, inputs and outputs, as far as their business functionality is concerned. However, any striking technical similarity between Rust and { C#, Java, Python, ... } implementations is indicative of deeper architectural problems. diff --git a/src/guidelines/ai/M-SINGLE-ITEM-PATH.md b/src/guidelines/ai/M-SINGLE-ITEM-PATH.md index a2eaa16..07904da 100644 --- a/src/guidelines/ai/M-SINGLE-ITEM-PATH.md +++ b/src/guidelines/ai/M-SINGLE-ITEM-PATH.md @@ -2,7 +2,7 @@ ## Items are only visible through one path (M-SINGLE-ITEM-PATH) { #M-SINGLE-ITEM-PATH } -to avoid confusion and clutter offering the same type multiple times. +to avoid confusion and clutter from offering the same type multiple times. 0.1 Public items within a crate should be reachable only through one path. For example some `crate::db::Connection` should not also be visible as `crate::Connection`: @@ -16,7 +16,7 @@ pub mod db { pub use db::Connection; ``` -This rule is often violated by agents creating or refactoring large code bases over several iterations. In an attempt to _simplify_ their task, they re-export items under a multiple paths, often previous ones before some change, instead of cleanly redesigning structures where it makes sense. +This rule is often violated by agents creating or refactoring large code bases over several iterations. In an attempt to _simplify_ their task, they re-export items under multiple paths, often previous ones from before some change, instead of cleanly redesigning structures where it makes sense. Note this only targets the duplication of user-facing items. Within a crate it is acceptable (and often unavoidable) to see the same item multiple times as export trees are constructed: @@ -29,4 +29,4 @@ pub(crate) mod db { pub use db::Connection; ``` -Similarly, re-exports of foreign items are not covered by this rule, although they should follow M-ORIGINAL-CRATES. +Similarly, re-exports of foreign items are not covered by this rule, although they should follow M-FOREIGN-REEXPORTS. diff --git a/src/guidelines/apps/M-TARGET-CPU.md b/src/guidelines/apps/M-TARGET-CPU.md index 0f462b1..3994493 100644 --- a/src/guidelines/apps/M-TARGET-CPU.md +++ b/src/guidelines/apps/M-TARGET-CPU.md @@ -7,7 +7,7 @@ Server applications should compile against the highest `target-cpu` that the deployment environment is guaranteed to support, rather than defaulting to the generic baseline. -This can be achieved by setting inside `.cargo/config.toml` for example +This can be achieved, for example, by setting inside `.cargo/config.toml`: ```toml [target.x86_64-unknown-linux-gnu] diff --git a/src/guidelines/checklist/README.md b/src/guidelines/checklist/README.md index b4f5f6d..63a3302 100644 --- a/src/guidelines/checklist/README.md +++ b/src/guidelines/checklist/README.md @@ -10,7 +10,7 @@ - [ ] Public types meant to be read are Display ([M-PUBLIC-DISPLAY]) - [ ] If in doubt, split the crate ([M-SMALLER-CRATES]) - [ ] Names are free of weasel words ([M-WEASEL-WORDS]) - - [ ] Names of items are generally short ([M-SHORT-NAMES]) + - [ ] Names of items are short ([M-SHORT-NAMES]) - [ ] Prefer regular over associated functions ([M-REGULAR-FN]) - [ ] Panic means 'stop the program' ([M-PANIC-IS-STOP]) - [ ] Detected programming bugs are panics, not errors ([M-PANIC-ON-BUG]) @@ -66,7 +66,7 @@ - [ ] Proc macros should have separate impl crate incl. tests ([M-PROC-IMPL]) - [ ] Proc macros don't produce implied or hidden items ([M-PROC-IMPLIED-ITEMS]) - **Applications** - - [ ] Use mimalloc for apps ([M-MIMALLOC-APP]) + - [ ] Use mimalloc for apps ([M-MIMALLOC-APPS]) - [ ] Applications may use Anyhow or derivatives ([M-APP-ERROR]) - [ ] Applications target highest viable target-cpu ([M-TARGET-CPU]) - **FFI** @@ -104,7 +104,7 @@ - [ ] AI-generated code requires human review ([M-HUMAN-REVIEW]) - [ ] Items are only visible through one path ([M-SINGLE-ITEM-PATH]) - [ ] Avoid meta design documentation ([M-NO-META-DESIGN-DOCUMENTATION]) - - [ ] Tests should not assert ground truth ([M-TAUTOLOGICAL-TESTS]) + - [ ] Tests do not assert ground truth ([M-TAUTOLOGICAL-TESTS]) - [ ] Rust code solves Rust problems ([M-RUST-SHAPED]) @@ -163,7 +163,7 @@ [M-APP-ERROR]: ../apps/#M-APP-ERROR -[M-MIMALLOC-APP]: ../apps/#M-MIMALLOC-APP +[M-MIMALLOC-APPS]: ../apps/#M-MIMALLOC-APPS [M-TARGET-CPU]: ../apps/#M-TARGET-CPU @@ -206,7 +206,6 @@ [M-MBE-OVER-PROC]: ../macros/#M-MBE-OVER-PROC [M-MACROS-DONT-LIE]: ../macros/#M-MACROS-DONT-LIE [M-MACRO-MAIN-CRATE]: ../macros/#M-MACRO-MAIN-CRATE -[M-MACROS-USE-MAIN-CRATE]: ../macros/#M-MACROS-USE-MAIN-CRATE [M-MACRO-HELPERS]: ../macros/#M-MACRO-HELPERS [M-PROC-IMPL]: ../macros/#M-PROC-IMPL [M-PROC-IMPLIED-ITEMS]: ../macros/#M-PROC-IMPLIED-ITEMS diff --git a/src/guidelines/ffi/M-FFI-NAMING.md b/src/guidelines/ffi/M-FFI-NAMING.md index 53d1ff0..41aab65 100644 --- a/src/guidelines/ffi/M-FFI-NAMING.md +++ b/src/guidelines/ffi/M-FFI-NAMING.md @@ -2,7 +2,7 @@ ## FFI crates follow established naming conventions (M-FFI-NAMING) { #M-FFI-NAMING } -to make the role crates immediately recognizable across projects. +to make the role of crates immediately recognizable across projects. 0.1 Crates used for FFI should follow established naming practices: diff --git a/src/guidelines/ffi/M-FFI-TRANSLATES.md b/src/guidelines/ffi/M-FFI-TRANSLATES.md index f039182..b015a8a 100644 --- a/src/guidelines/ffi/M-FFI-TRANSLATES.md +++ b/src/guidelines/ffi/M-FFI-TRANSLATES.md @@ -2,7 +2,7 @@ ## Business logic belongs in core crates, FFI only translates (M-FFI-TRANSLATES) { #M-FFI-TRANSLATES } -to maximize safe code and have clean separation of concerns. +to maximize safe code and have a clean separation of concerns. 0.1 When Rust is used to create FFI libraries, there should be a clear separation of concerns between the core _business logic_ crate `foo` and the glue crate `foo-ffi`. diff --git a/src/guidelines/libs/interop/M-FOREIGN-REEXPORTS.md b/src/guidelines/libs/interop/M-FOREIGN-REEXPORTS.md index 86676cd..ad6b3ad 100644 --- a/src/guidelines/libs/interop/M-FOREIGN-REEXPORTS.md +++ b/src/guidelines/libs/interop/M-FOREIGN-REEXPORTS.md @@ -7,7 +7,7 @@ Crates should generally not re-export items from other crates. For example, if your crate contains a method `foo::download(url: bar::Url)`, you should not do `pub use bar::Url` from inside `foo`. This avoids having possibly dozens of aliases in context, which can get confusing for both users and agents, in particular if these are mixed with genuinely different types of the same name from other crates. -When a crate accepts or returns a type defined in some third-party crate, users are be expected to depend on that third-party crate directly and import the type from there. That said, there are a few valid exceptions to this rule: +When a crate accepts or returns a type defined in some third-party crate, users are expected to depend on that third-party crate directly and import the type from there. That said, there are a few valid exceptions to this rule: - Umbrella crates (compare M-DONT-LEAK-TYPES) by definition re-export other types - Crates split for technical reasons (e.g., exporting `foo_core::Url` from `foo`) diff --git a/src/guidelines/libs/resilience/M-INTEGRATION-TESTS.md b/src/guidelines/libs/resilience/M-INTEGRATION-TESTS.md index 8aa2d2d..82e9fc8 100644 --- a/src/guidelines/libs/resilience/M-INTEGRATION-TESTS.md +++ b/src/guidelines/libs/resilience/M-INTEGRATION-TESTS.md @@ -7,4 +7,4 @@ Tests that only touch public API surface are _integration tests_ and belong under `tests/`, not `mod tests {}`. -In projects with coverage targets, it is not uncommon for `src/` files to contain more testing code than actual business logic. This can make browsing and understanding the code harder both in IDEs and PRs. Likewise, if a testing goal can be achieved through either an integration test or a unit test, the former is always preferred. Shared helpers between integration tests should live in a subdirectory module, e.g. `tests/common/mod.rs`. +In projects with coverage targets, it is not uncommon for `src/` files to contain more testing code than actual business logic. This can make browsing and understanding the code harder both in IDEs and PRs. Likewise, if a testing goal can be achieved through either an integration test or a unit test, the former is always preferred. Shared helpers between integration tests should live in a subdirectory module, e.g., `tests/common/mod.rs`. diff --git a/src/guidelines/libs/resilience/M-PANIC-CONTINUATION.md b/src/guidelines/libs/resilience/M-PANIC-CONTINUATION.md index 396dc65..e604cd0 100644 --- a/src/guidelines/libs/resilience/M-PANIC-CONTINUATION.md +++ b/src/guidelines/libs/resilience/M-PANIC-CONTINUATION.md @@ -29,6 +29,6 @@ fn main() { } ``` -Although the example above is slightly contrived, the side effects and interactions of a caught panic can harder to identify, can have wider blast radius, and be subtle. +Although the example above is slightly contrived, the side effects and interactions of a caught panic can be harder to identify, can have wider blast radius, and be subtle. -Systems where many unrelated tasks are in flight (e.g., server request handler) can use `catch_unwind` on a per-request basis, but should still promote an application restart after a request handler caused a panic. The purpose of `catch_unwind` here is not to continue execution indefinitely, but to allow all other requests to gracefully finish. +Systems where many unrelated tasks are in flight (e.g., server request handlers) can use `catch_unwind` on a per-request basis, but should still promote an application restart after a request handler caused a panic. The purpose of `catch_unwind` here is not to continue execution indefinitely, but to allow all other requests to gracefully finish. diff --git a/src/guidelines/libs/resilience/M-STRONG-TYPES-GUARD.md b/src/guidelines/libs/resilience/M-STRONG-TYPES-GUARD.md index 2bf353c..ab3705d 100644 --- a/src/guidelines/libs/resilience/M-STRONG-TYPES-GUARD.md +++ b/src/guidelines/libs/resilience/M-STRONG-TYPES-GUARD.md @@ -5,7 +5,7 @@ To centralize essential correctness invariants. 0.1 -When introducing a strong type or newtype that exists to encode an invariant (a non-empty string, a percentage, a port number, a sanitized path, ...) the type itself must enforce that invariant where applicable. +When introducing a strong type or newtype that exists to encode an invariant (a non-empty string, a percentage, a port number, a sanitized path, ...), the type itself must enforce that invariant where applicable. Construction should be fallible, returning a proper error when the invariant cannot be upheld, rather than handing the responsibility off to every user: diff --git a/src/guidelines/libs/ux/M-BALANCED-MODULES.md b/src/guidelines/libs/ux/M-BALANCED-MODULES.md index 02404cf..d5537d1 100644 --- a/src/guidelines/libs/ux/M-BALANCED-MODULES.md +++ b/src/guidelines/libs/ux/M-BALANCED-MODULES.md @@ -7,7 +7,7 @@ Your module design should approximately follow established UX practices of menu design: A _reasonable_ number of your most important items should be placed in the crate root, and a comprehensible grouping of the remaining functionality into subordinate modules. -The two violations of that rule that can be encountered most frequently: flat module roots containing dozens of items without clear ordering, or the excessive use of submodules without items in the crate root. While there are crates where this makes sense (e.g., automatically generated `-sys` crates defining 100s of C items, or umbrella crates like `std` and `tokio`), the majority of library crates are not among them. +Two violations of that rule are encountered most frequently: flat module roots containing dozens of items without clear ordering, or the excessive use of submodules without items in the crate root. While there are crates where this makes sense (e.g., automatically generated `-sys` crates defining 100s of C items, or umbrella crates like `std` and `tokio`), the majority of library crates are not among them. When designing your module layout, consider these factors: diff --git a/src/guidelines/libs/ux/M-NO-PRELUDE.md b/src/guidelines/libs/ux/M-NO-PRELUDE.md index 2987dda..57eb772 100644 --- a/src/guidelines/libs/ux/M-NO-PRELUDE.md +++ b/src/guidelines/libs/ux/M-NO-PRELUDE.md @@ -7,7 +7,7 @@ Crates must not define a `prelude` or any namespace intended to be imported as `use foo::*`. -While the Rust Standard Library successfully uses [preludes](https://doc.rust-lang.org/std/prelude/index.html) to define edition items, preludes in crates cause more harm than good. Given today's IDE support they are not needed, and once multiple preludes are used from same crate there is potential for conflicts: +While the Rust Standard Library successfully uses [preludes](https://doc.rust-lang.org/std/prelude/index.html) to define edition items, preludes in crates cause more harm than good. Given today's IDE support they are not needed, and once multiple preludes are used from different crates there is potential for conflicts: ```rust use foo::prelude::*; diff --git a/src/guidelines/macros/M-MACRO-LAST-RESORT.md b/src/guidelines/macros/M-MACRO-LAST-RESORT.md index 32f4c94..db26b23 100644 --- a/src/guidelines/macros/M-MACRO-LAST-RESORT.md +++ b/src/guidelines/macros/M-MACRO-LAST-RESORT.md @@ -11,10 +11,10 @@ Macros should only be used if no other viable solution exists, compare this adag > > @pcwalton -Macros are powerful, but come with several downsides, they +Macros are powerful, but come with several downsides. They -- are magic, and can be impossible to predict what they do, or how they do it, +- are magic, and it can be impossible to predict what they do, or how they do it, - disproportionally increase compilation time in projects that otherwise don't rely on them, - can cause subtle breakage at edition boundaries where Rust syntax and semantics can change. -Counterintuitively, the more structurally complex the result of a macro expansion is, the worse of an idea it is to use macros for that in the first place. The ideal macro makes your users go "_I know exactly what this will generate, but I don't want to write all of that by hand_". +Counterintuitively, the more structurally complex the result of a macro expansion is, the worse an idea it is to use macros for that in the first place. The ideal macro makes your users go "_I know exactly what this will generate, but I don't want to write all of that by hand_". diff --git a/src/guidelines/macros/M-MACRO-MAIN-CRATE.md b/src/guidelines/macros/M-MACRO-MAIN-CRATE.md index ed5d01d..aeaa3ed 100644 --- a/src/guidelines/macros/M-MACRO-MAIN-CRATE.md +++ b/src/guidelines/macros/M-MACRO-MAIN-CRATE.md @@ -13,5 +13,4 @@ For crates including proc macros it is common to ship them split in 3 for techni - `foo_proc` - facade re-exporting macros from `foo_proc_impl` with `proc-macro = true`, - `foo_proc_impl` - the actual macro implementation and unit tests. -In some cases there can be additional crates involved. Authors might be tempted trying to make both `foo`, `foo_proc`, and siblings work, resulting in complex -re-export hierarchies or the use of 3rd party helpers. In reality, the minimal UX gain is usually not worth added complexity (or compile time overhead), given the ecosystem precedent of mostly not supporting these usage modes in the first place. +In some cases there can be additional crates involved. Authors might be tempted to make `foo`, `foo_proc`, and siblings all work, resulting in complex re-export hierarchies or the use of 3rd party helpers. In reality, the minimal UX gain is usually not worth the added complexity (or compile time overhead), given the ecosystem precedent of mostly not supporting these usage modes in the first place. diff --git a/src/guidelines/macros/M-MACROS-DONT-LIE.md b/src/guidelines/macros/M-MACROS-DONT-LIE.md index e24632c..67742e7 100644 --- a/src/guidelines/macros/M-MACROS-DONT-LIE.md +++ b/src/guidelines/macros/M-MACROS-DONT-LIE.md @@ -5,7 +5,7 @@ To avoid confusing users and LLMs. 0.1 -Macros must not (make users) misrepresent signatures or shape of items. +Macros must not (make users) misrepresent signatures or the shape of items. Macros have the ability to arbitrarily rewrite token streams. They could convert structs to enums, traits to functions, or perform any other transformation imaginable. They should, however, do none of that, as the resulting code will be highly confusing and virtually impossible to predict or reason about. diff --git a/src/guidelines/macros/M-MBE-OVER-PROC.md b/src/guidelines/macros/M-MBE-OVER-PROC.md index 34b4a27..e7f60e3 100644 --- a/src/guidelines/macros/M-MBE-OVER-PROC.md +++ b/src/guidelines/macros/M-MBE-OVER-PROC.md @@ -7,7 +7,7 @@ When a 'macro by example' can do the job, it should be preferred over proc macros. -Proc macros are more powerful, but their expansion can't easily be inspected. Where this versatility isn't needed, a simple 'macro by expansion' is the better option. +Proc macros are more powerful, but their expansion can't easily be inspected. Where this versatility isn't needed, a simple 'macro by example' is the better option. ```rust // Bad, attribute macro requires proc macro machinery, can be hard to diff --git a/src/guidelines/macros/M-PROC-HARDCODED-TYPES.md b/src/guidelines/macros/M-PROC-HARDCODED-TYPES.md deleted file mode 100644 index 24f4afc..0000000 --- a/src/guidelines/macros/M-PROC-HARDCODED-TYPES.md +++ /dev/null @@ -1,54 +0,0 @@ - - -## Proc macros don't hardcode types (M-PROC-HARDCODED-TYPES) { #M-PROC-HARDCODED-TYPES } - -To avoid confusing errors, hygiene and visibility issues. -0.1 - -Macros should not define magic types on their own, in particular not public ones, or ones that don't rely on namespace tricks. - -Some macro want to define types, for example - -```rust -#[my_macro] -struct UserType; - -// would expand to - -struct UserType; -struct ExtraType; - -impl UserType { - fn foo() -> ExtraType { ... }; -} -``` - -This is almost always a bad idea for several reasons: - -- they can conflict with existing user-defined types inside the same module, -- if done naively, they can conflict with other expansions of the same macro, -- they can clash with the user's naming conventions, -- they are invisible at source code level and easily forgotten to be re-exported where needed. - -While it is possible for users to work around these limitations somewhat, these are paper cuts your users will have to deal with, possibly months after the fact when refactoring otherwise unrelated code. - -Note that there is one exception to this rule that has generally acceptable UX, the overloaded use of [namespaces](https://doc.rust-lang.org/reference/names/namespaces.html) made prominent by crates like Rocket: - -```rust -#[my_macro] -fn foo() { ... } - -// would expand to - -fn foo() { ... } - -struct foo; -impl SomeTrait for foo { ... } -``` - -Here a new type `foo` is introduced with the same name as the function `foo`. Due to Rust's namespace rules they can co-exit and are automatically re-exported with their parent, and due to [Rust's casing rules (C-CASE)](https://rust-lang.github.io/api-guidelines/naming.html#casing-conforms-to-rfc-430-c-case) these are highly unlikely to clash with user-defined types. However, they would still not make for a pretty _public_ type, and are therefore mainly used inside root crates to define request handlers or FFI functions. - -> ### Namespaces != Modules -> -> Namespaces in Rust have nothing to do with namespaces in other languages. A namespace in C# is approximately a module in Rust. A namespace in Rust -is an esoteric property of names (e.g., `fn foo`, `struct Bar {}`, `moo!`) that decides which 'naming bucket' it lives in inside a module. diff --git a/src/guidelines/macros/M-PROC-IMPL.md b/src/guidelines/macros/M-PROC-IMPL.md index 606f326..03ac77e 100644 --- a/src/guidelines/macros/M-PROC-IMPL.md +++ b/src/guidelines/macros/M-PROC-IMPL.md @@ -7,7 +7,7 @@ Proc macros should be thin shims inside some `foo_proc` crate that delegate to a separate, regular library crate, usually called `foo_proc_impl`, which contains the actual token-stream transformation logic and its tests. -As proc macro crates are special, testing them from `foo_proc` usually requires workaround for unit and snapshot tests. Instead, consider having a `foo_proc_impl` crate: +As proc macro crates are special, testing them from `foo_proc` usually requires workarounds for unit and snapshot tests. Instead, consider having a `foo_proc_impl` crate: ```rust use proc_macro2::TokenStream; diff --git a/src/guidelines/macros/M-PROC-IMPLIED-ITEMS.md b/src/guidelines/macros/M-PROC-IMPLIED-ITEMS.md index 97b540a..de5851c 100644 --- a/src/guidelines/macros/M-PROC-IMPLIED-ITEMS.md +++ b/src/guidelines/macros/M-PROC-IMPLIED-ITEMS.md @@ -7,7 +7,7 @@ Macros should not define magic types on their own, in particular not public ones, or ones that don't rely on namespace tricks. -Some macro want to define types, for example +Some macros want to define types, for example ```rust #[my_macro] @@ -46,7 +46,7 @@ struct foo; impl SomeTrait for foo { ... } ``` -Here a new type `foo` is introduced with the same name as the function `foo`. Due to Rust's namespace rules they can co-exit and are automatically re-exported with their parent, and due to [Rust's casing rules (C-CASE)](https://rust-lang.github.io/api-guidelines/naming.html#casing-conforms-to-rfc-430-c-case) these are highly unlikely to clash with user-defined types. However, they would still not make for a pretty _public_ type, and are therefore mainly used inside root crates to define request handlers or FFI functions. +Here a new type `foo` is introduced with the same name as the function `foo`. Due to Rust's namespace rules they can co-exist and are automatically re-exported with their parent, and due to [Rust's casing rules (C-CASE)](https://rust-lang.github.io/api-guidelines/naming.html#casing-conforms-to-rfc-430-c-case) these are highly unlikely to clash with user-defined types. However, they would still not make for a pretty _public_ type, and are therefore mainly used inside root crates to define request handlers or FFI functions. > ### Namespaces != Modules > diff --git a/src/guidelines/performance/M-AVOID-INDIRECTION.md b/src/guidelines/performance/M-AVOID-INDIRECTION.md index 4674d48..e9d3297 100644 --- a/src/guidelines/performance/M-AVOID-INDIRECTION.md +++ b/src/guidelines/performance/M-AVOID-INDIRECTION.md @@ -7,9 +7,9 @@ Hot types should avoid nested heap indirection and consider lifting hot, cacheable deep fields to improve cache utilization. -While the gold standard is to benchmark, a pattern that emerges repeatedly when porting code C# code to Rust is to reflexively `Arc`ing nested types, often multiple layers deep. Although this can make sense on very wide or heavyweight types that genuinely need to be shared by multiple owners, this pattern can ruin access latency when multiple rounds of DRAM lookup have to be performed sequentially. +While the gold standard is to benchmark, a pattern that emerges repeatedly when porting C# code to Rust is to reflexively `Arc` nested types, often multiple layers deep. Although this can make sense on very wide or heavyweight types that genuinely need to be shared by multiple owners, this pattern can ruin access latency when multiple rounds of DRAM lookup have to be performed sequentially. -Where nested, shared ownership isn't strictly needed, it is usually better to start with local, embedded data, and lifted cacheable fields. +Where nested, shared ownership isn't strictly needed, it is usually better to start with local, embedded data, and lift cacheable fields. ```rust // Bad, `print` (assuming it is reasonably hot) needs 2 indirections diff --git a/src/guidelines/performance/M-BOX-DST.md b/src/guidelines/performance/M-BOX-DST.md index 7b739e1..912a8ee 100644 --- a/src/guidelines/performance/M-BOX-DST.md +++ b/src/guidelines/performance/M-BOX-DST.md @@ -9,17 +9,16 @@ Frequently used, internal, immutable sequences that will not be resized after co 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: -- 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 +- 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. Some collections provide dedicated methods for this, e.g., `String::into_boxed_str`. ```rust // Bad, with many entries this wastes space and makes -// traversal ultimately slower. The internal representation -// won't +// traversal ultimately slower. struct Data { ids: Vec } diff --git a/src/guidelines/performance/M-INITIAL-CAPACITY.md b/src/guidelines/performance/M-INITIAL-CAPACITY.md index 763fc57..abeb243 100644 --- a/src/guidelines/performance/M-INITIAL-CAPACITY.md +++ b/src/guidelines/performance/M-INITIAL-CAPACITY.md @@ -7,10 +7,10 @@ Where the final or approximate size of a collection (`Vec`, `String`, `HashMap`, `HashSet`, etc.) is known at construction time, it should be created via `with_capacity` rather than `new` or `default`. -Collections created without capacity may be re-allocated multiple times during their initialization, which also includes copying their content. Creating them with sufficient capacity an entirely avoid this needless overhead. +Collections created without capacity may be re-allocated multiple times during their initialization, which also includes copying their content. Creating them with sufficient capacity can entirely avoid this needless overhead. ```rust -// Bad, probably re-allocates and copies concent over multiple times. +// Bad, probably re-allocates and copies content over multiple times. let mut rval = Vec::new(); for x in &other { rval.push(convert(x)); diff --git a/src/guidelines/performance/M-LOG-OVERHEAD.md b/src/guidelines/performance/M-LOG-OVERHEAD.md index 3257b64..8e1bda6 100644 --- a/src/guidelines/performance/M-LOG-OVERHEAD.md +++ b/src/guidelines/performance/M-LOG-OVERHEAD.md @@ -19,10 +19,10 @@ for m in messages { // Better, avoids per-message allocations. for m in messages { - log(("Emitting message", m.id()) + log(("Emitting message", m.id())) } // Best: If possible, let telemetry users reconstruct what happened offline -log(("Processing message batch", messages.batch_id()) +log(("Processing message batch", messages.batch_id())) for m in messages { ... } ``` diff --git a/src/guidelines/performance/M-MEM-REUSE.md b/src/guidelines/performance/M-MEM-REUSE.md index b6fcc6b..d7b6e35 100644 --- a/src/guidelines/performance/M-MEM-REUSE.md +++ b/src/guidelines/performance/M-MEM-REUSE.md @@ -15,7 +15,7 @@ for id in ids { let value = db.get(id); } ``` -While these style of APIs may exist for convenience, they should be auxiliary. Instead, the core APIs should allow users to own the underlying object and re-use it: +While this style of API may exist for convenience, it should be auxiliary. Instead, the core APIs should allow users to own the underlying object and re-use it: ```rust // Good, allows users to decide whether a new allocation is needed. @@ -32,7 +32,7 @@ struct Value { data: Vec } ``` -In heavyweight, deeply nested libraries it can be worthwhile to either pass a bump-style `Arena`, or to encapsulate one inside the user types, so it can used throughout the call stack: +In heavyweight, deeply nested libraries it can be worthwhile to either pass a bump-style `Arena`, or to encapsulate one inside the user types, so it can be used throughout the call stack: ```rust struct Query { diff --git a/src/guidelines/performance/M-SHRINK-TO-FIT.md b/src/guidelines/performance/M-SHRINK-TO-FIT.md index 8f2aeeb..82126b4 100644 --- a/src/guidelines/performance/M-SHRINK-TO-FIT.md +++ b/src/guidelines/performance/M-SHRINK-TO-FIT.md @@ -5,7 +5,7 @@ To reduce memory footprint. 0.1 -Where large, long-lived, growable collection such as `Vec`, `String` were built without an exact size reservation (compare M-INITIAL-CAPACITY), the resulting collection should be shrunk via `shrink_to_fit` before storing it. +Where large, long-lived, growable collections such as `Vec` or `String` were built without an exact size reservation (compare M-INITIAL-CAPACITY), the resulting collection should be shrunk via `shrink_to_fit` before storing it. Rust's collections grow by powers of two when iteratively adding elements. In the worst case a collection might therefore use ~2x of its needed memory. @@ -19,4 +19,4 @@ for x in large_iter { // Good, frees up extra memory. long_lived.shrink_to_fit(); ``` -Note, this does not apply to conversions done via `into_boxed_` and friends (compare M-BOX-DST), as these generally shrink before converting already. +Note that this does not apply to conversions done via `into_boxed_*` and friends (compare M-BOX-DST), as these generally shrink before converting already. diff --git a/src/guidelines/project/M-CARGO-WORKSPACE.md b/src/guidelines/project/M-CARGO-WORKSPACE.md index d270f9a..888d0e4 100644 --- a/src/guidelines/project/M-CARGO-WORKSPACE.md +++ b/src/guidelines/project/M-CARGO-WORKSPACE.md @@ -5,6 +5,6 @@ To ensure consistent, maintainable project configuration. 0.1 -Any repo with two or more crates that somehow belong together should unify these crates with a workspace `Cargo.toml`. Member then inherit shared metadata and dependency versions from the workspace root via `[workspace.dependencies]`, `[workspace.lints]`, ... rather than duplicating these values in each crate. +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. diff --git a/src/guidelines/project/M-CRATES-FLAT-FOLDER.md b/src/guidelines/project/M-CRATES-FLAT-FOLDER.md index 141620b..85d331a 100644 --- a/src/guidelines/project/M-CRATES-FLAT-FOLDER.md +++ b/src/guidelines/project/M-CRATES-FLAT-FOLDER.md @@ -5,6 +5,6 @@ To simplify project navigation and follow established Rust standards. 0.1 -All crates in a workspace live as direct subdirectories of a single folder (e.g., `crates/`). In rare cases this rule can be broken where two or more aggregation hierarchies exist, such as differentiating unpublished crates from released ones (e.g. `crates/` and `crates_internal/`), or third-party from own (e.g., `vendored/`). +All crates in a workspace live as direct subdirectories of a single folder (e.g., `crates/`). In rare cases this rule can be broken where two or more aggregation hierarchies exist, such as differentiating unpublished crates from released ones (e.g., `crates/` and `crates_internal/`), or third-party crates from own (e.g., `vendored/`). -Placing crates inside other crates (at or below their `Cargo.toml`), or even inside their `src/` folder is never acceptable. If a crate relation should be expressed, this is done via common prefixes instead (e.g., `foo`, `foo_util`, `foo_build`). +Placing crates inside other crates (at or below their `Cargo.toml`), or even inside their `src/` folder is never acceptable. If a crate relationship should be expressed, this is done via common prefixes instead (e.g., `foo`, `foo_util`, `foo_build`). diff --git a/src/guidelines/project/M-LATEST-EDITION.md b/src/guidelines/project/M-LATEST-EDITION.md index 262a92c..af39411 100644 --- a/src/guidelines/project/M-LATEST-EDITION.md +++ b/src/guidelines/project/M-LATEST-EDITION.md @@ -7,4 +7,4 @@ When creating a new crate or workspace, set `edition` to the latest stable edition (at least `2024` at the time of writing); the `resolver` field is generally not needed. -Using an older edition has generally no upsides for new projects, but forces you to write 'old Rust' that is less idiomatic and has worse UX edge cases. Notably, using an older edition does _not_ grant any compatibility benefits with the rest of the ecosystem. An application based on `2015` can use libraries written for `2024` just fine. +Using an older edition generally has no upsides for new projects, but forces you to write 'old Rust' that is less idiomatic and has worse UX edge cases. Notably, using an older edition does _not_ grant any compatibility benefits with the rest of the ecosystem. An application based on `2015` can use libraries written for `2024` just fine. diff --git a/src/guidelines/project/M-MSRV.md b/src/guidelines/project/M-MSRV.md index 79d3635..671ee8a 100644 --- a/src/guidelines/project/M-MSRV.md +++ b/src/guidelines/project/M-MSRV.md @@ -9,4 +9,4 @@ A Minimum Supported Rust Version (MSRV) should be set when libraries are first c The ecosystem expectation is that projects are compiled with a _reasonably modern_ Rust compiler. -Bumping MSRV does therefore not require a major release, but can be handled through a minor update (e.g., `1.3` to `1.4`). In fact, any project depending on 3rd party crates is already inherently bound to this contract, thus forcing a major version bump will not confer any benefits, but could possibly bifurcate downstream dependencies. +Bumping MSRV therefore does not require a major release, but can be handled through a minor update (e.g., `1.3` to `1.4`). In fact, any project depending on 3rd party crates is already inherently bound to this contract; forcing a major version bump will not confer any benefits, but could possibly bifurcate downstream dependencies. diff --git a/src/guidelines/universal/M-WEASEL-WORDS.md b/src/guidelines/universal/M-WEASEL-WORDS.md index 18bf374..33095e6 100644 --- a/src/guidelines/universal/M-WEASEL-WORDS.md +++ b/src/guidelines/universal/M-WEASEL-WORDS.md @@ -5,8 +5,8 @@ To improve readability. 1.0 -Symbol names, especially types and traits names, should be free of weasel words that do not meaningfully -add information. Common offenders include `Service`, `Manager`, and `Factory`. For example: +Symbol names, especially type and trait names, should be free of weasel words that do not meaningfully +add information. Common offenders include `Service`, `Manager`, and `Factory`. While your library may very well contain or communicate with a booking service—or even hold an `HttpClient` instance named `booking_service`—one should rarely encounter a `BookingService` _type_ in code. @@ -14,7 +14,7 @@ instance named `booking_service`—one should rarely encounter a `BookingSer An item handling many bookings can just be called `Bookings`. If it does anything more specific, then that quality should be appended instead. It submits these items elsewhere? Calling it `BookingDispatcher` would be more helpful. -The same is true for `Manager`s. Every code manages _something_, so that moniker is rarely useful. With rare +The same is true for `Manager`s. All code manages _something_, so that moniker is rarely useful. With rare exceptions, life cycle issues should likewise not be made the subject of some manager. Items are created in whatever way they are needed, their disposal is governed by `Drop`, and only `Drop`. From 369fb00859069b17e0df695f9f60aef1e9b67aec Mon Sep 17 00:00:00 2001 From: Ralf Biedert Date: Fri, 5 Jun 2026 16:49:11 +0200 Subject: [PATCH 08/10] Crosslink guidelines. --- src/guidelines/ai/M-HUMAN-REVIEW.md | 4 ++-- src/guidelines/ai/M-RUST-SHAPED.md | 2 +- src/guidelines/ai/M-SINGLE-ITEM-PATH.md | 2 +- src/guidelines/checklist/README.md | 2 +- src/guidelines/libs/interop/M-FOREIGN-REEXPORTS.md | 2 +- src/guidelines/libs/resilience/M-PANIC-CONTINUATION.md | 2 +- src/guidelines/libs/ux/M-BUILD-RESULT.md | 4 ++-- src/guidelines/libs/ux/M-COLLECTION-TRAITS.md | 2 +- src/guidelines/libs/ux/M-FROM-ERROR.md | 4 ++-- src/guidelines/libs/ux/M-NO-PRELUDE.md | 2 +- src/guidelines/libs/ux/M-PARAMETER-ORDER.md | 2 +- src/guidelines/performance/M-SHRINK-TO-FIT.md | 4 ++-- src/guidelines/universal/M-LOG-NOT-PRINT.md | 4 ++-- src/guidelines/universal/M-SHORT-NAMES.md | 4 ++-- 14 files changed, 20 insertions(+), 20 deletions(-) diff --git a/src/guidelines/ai/M-HUMAN-REVIEW.md b/src/guidelines/ai/M-HUMAN-REVIEW.md index 866b21e..2e09427 100644 --- a/src/guidelines/ai/M-HUMAN-REVIEW.md +++ b/src/guidelines/ai/M-HUMAN-REVIEW.md @@ -9,11 +9,11 @@ Agents can do a great job authoring APIs within minutes that would take you othe Rust has the advantage over many other languages of a strong type system to force correctness at compile time, and to design APIs that are fast and hard to misuse. Good API design can greatly aid in forcing a correct implementation. -However, as APIs also define contracts between you and your users, bad choices can have viral effects (e.g., compare M-AVOID-WRAPPERS, M-AVOID-STATICS) and cannot easily be verified. +However, as APIs also define contracts between you and your users, bad choices can have viral effects (e.g., compare [M-AVOID-WRAPPERS](../libs/ux/#M-AVOID-WRAPPERS), [M-AVOID-STATICS](../libs/resilience/#M-AVOID-STATICS)) and cannot easily be verified. Before submitting major PRs or releasing new APIs you and/or other human reviewers must check that all guidelines and other requirements are adhered to, and that the overall API looks reasonable. -In particular, ensure all public APIs follow these guidelines and M-UPSTREAM-GUIDELINES. You may use LLMs to point out where these guidelines are not met, but (until model fidelity improves) you cannot take your agent's word that the guidelines are met. +In particular, ensure all public APIs follow these guidelines and [M-UPSTREAM-GUIDELINES](../universal/#M-UPSTREAM-GUIDELINES). You may use LLMs to point out where these guidelines are not met, but (until model fidelity improves) you cannot take your agent's word that the guidelines are met. diff --git a/src/guidelines/ai/M-RUST-SHAPED.md b/src/guidelines/ai/M-RUST-SHAPED.md index 6662cab..d98a508 100644 --- a/src/guidelines/ai/M-RUST-SHAPED.md +++ b/src/guidelines/ai/M-RUST-SHAPED.md @@ -17,6 +17,6 @@ However, many patterns exist to solve problems particular to the ecosystem they - ownership of parameters, - and many others. -While some language constructs simply don't translate at all (e.g., compared to C#, Rust does not have any meaningful reflection), others are deceptively similar and might only bite months down the line (e.g., statics, compare M-AVOID-STATICS). +While some language constructs simply don't translate at all (e.g., compared to C#, Rust does not have any meaningful reflection), others are deceptively similar and might only bite months down the line (e.g., statics, compare [M-AVOID-STATICS](../libs/resilience/#M-AVOID-STATICS)). As a rule of thumb, structs and their methods can have vaguely similar names, flows, inputs and outputs, as far as their business functionality is concerned. However, any striking technical similarity between Rust and { C#, Java, Python, ... } implementations is indicative of deeper architectural problems. diff --git a/src/guidelines/ai/M-SINGLE-ITEM-PATH.md b/src/guidelines/ai/M-SINGLE-ITEM-PATH.md index 07904da..ff6ecc5 100644 --- a/src/guidelines/ai/M-SINGLE-ITEM-PATH.md +++ b/src/guidelines/ai/M-SINGLE-ITEM-PATH.md @@ -29,4 +29,4 @@ pub(crate) mod db { pub use db::Connection; ``` -Similarly, re-exports of foreign items are not covered by this rule, although they should follow M-FOREIGN-REEXPORTS. +Similarly, re-exports of foreign items are not covered by this rule, although they should follow [M-FOREIGN-REEXPORTS](../libs/interop/#M-FOREIGN-REEXPORTS). diff --git a/src/guidelines/checklist/README.md b/src/guidelines/checklist/README.md index 63a3302..32ae890 100644 --- a/src/guidelines/checklist/README.md +++ b/src/guidelines/checklist/README.md @@ -42,7 +42,7 @@ - [ ] Parameter ordering is consistent across crates or ecosystem ([M-PARAMETER-CONSISTENCY]) - [ ] Important parameters go first, closures last ([M-PARAMETER-ORDER]) - [ ] Collections implement the appropriate iter traits ([M-COLLECTION-TRAITS]) - - [ ] Where possible functions are `async` over returning a Future ([M-ASYNC-FN]) + - [ ] Functions are `async` over returning a Future ([M-ASYNC-FN]) - **Library / Resilience** - [ ] I/O and system calls are mockable ([M-MOCKABLE-SYSCALLS]) - [ ] Test utilities are feature gated ([M-TEST-UTIL]) diff --git a/src/guidelines/libs/interop/M-FOREIGN-REEXPORTS.md b/src/guidelines/libs/interop/M-FOREIGN-REEXPORTS.md index ad6b3ad..4a44569 100644 --- a/src/guidelines/libs/interop/M-FOREIGN-REEXPORTS.md +++ b/src/guidelines/libs/interop/M-FOREIGN-REEXPORTS.md @@ -9,6 +9,6 @@ Crates should generally not re-export items from other crates. For example, if y When a crate accepts or returns a type defined in some third-party crate, users are expected to depend on that third-party crate directly and import the type from there. That said, there are a few valid exceptions to this rule: -- Umbrella crates (compare M-DONT-LEAK-TYPES) by definition re-export other types +- Umbrella crates (compare [M-DONT-LEAK-TYPES](#M-DONT-LEAK-TYPES)) by definition re-export other types - Crates split for technical reasons (e.g., exporting `foo_core::Url` from `foo`) - Macro use to provide stable paths, e.g., via some hidden `foo::__private::Url` diff --git a/src/guidelines/libs/resilience/M-PANIC-CONTINUATION.md b/src/guidelines/libs/resilience/M-PANIC-CONTINUATION.md index e604cd0..73b7305 100644 --- a/src/guidelines/libs/resilience/M-PANIC-CONTINUATION.md +++ b/src/guidelines/libs/resilience/M-PANIC-CONTINUATION.md @@ -7,7 +7,7 @@ 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 and 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: +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: ```rust thread_local! { diff --git a/src/guidelines/libs/ux/M-BUILD-RESULT.md b/src/guidelines/libs/ux/M-BUILD-RESULT.md index 7587098..7641938 100644 --- a/src/guidelines/libs/ux/M-BUILD-RESULT.md +++ b/src/guidelines/libs/ux/M-BUILD-RESULT.md @@ -11,5 +11,5 @@ A builder's per-field setter methods should accept input without failing. All cr - TODO: Clarify whether setters may ever return `Result` (e.g., for parsing-style inputs) or whether they must always be infallible. - TODO: Specify how errors should aggregate (single error vs. collected errors for multiple problems). - TODO: Provide a concrete bad example (a setter that returns `Result`, or validation scattered across setters). -- TODO: Provide a concrete good example (infallible chainable setters; `.build()` returns `Result` with a canonical error type per M-ERRORS-CANONICAL-STRUCTS). -- TODO: Note interaction with M-INIT-BUILDER and M-INIT-CASCADED. +- TODO: Provide a concrete good example (infallible chainable setters; `.build()` returns `Result` with a canonical error type per [M-ERRORS-CANONICAL-STRUCTS](#M-ERRORS-CANONICAL-STRUCTS)). +- TODO: Note interaction with [M-INIT-BUILDER](#M-INIT-BUILDER) and [M-INIT-CASCADED](#M-INIT-CASCADED). diff --git a/src/guidelines/libs/ux/M-COLLECTION-TRAITS.md b/src/guidelines/libs/ux/M-COLLECTION-TRAITS.md index 4bebd7f..4a117d8 100644 --- a/src/guidelines/libs/ux/M-COLLECTION-TRAITS.md +++ b/src/guidelines/libs/ux/M-COLLECTION-TRAITS.md @@ -12,5 +12,5 @@ Custom collection types should implement the iterator-facing traits the standard - TODO: Note when *not* to implement a given trait (e.g., `FromIterator` for collections that need extra context to construct). - TODO: Provide a concrete bad example (a custom collection missing `IntoIterator for &Collection` so users cannot iterate by reference in a `for` loop). - TODO: Provide a concrete good example. -- TODO: Note interaction with M-ESSENTIAL-FN-INHERENT and M-IMPL-ASREF. +- TODO: Note interaction with [M-ESSENTIAL-FN-INHERENT](#M-ESSENTIAL-FN-INHERENT) and [M-IMPL-ASREF](#M-IMPL-ASREF). diff --git a/src/guidelines/libs/ux/M-FROM-ERROR.md b/src/guidelines/libs/ux/M-FROM-ERROR.md index e227637..d3f1a07 100644 --- a/src/guidelines/libs/ux/M-FROM-ERROR.md +++ b/src/guidelines/libs/ux/M-FROM-ERROR.md @@ -8,7 +8,7 @@ Conversions between error types that are part of the project's canonical error hierarchy should be implemented as `impl From for TargetError` (typically via `#[from]` on a `thiserror`-style derive or an explicit impl) and used implicitly via `?`. Call sites should not reach for `.map_err(...)` to perform the same conversion repeatedly. - TODO: Specify when `map_err` is still appropriate (one-off context attachment, lossy summarization, conversions that depend on local context the `From` impl cannot see). -- TODO: Clarify the policy for canonical error structs (cf. M-ERRORS-CANONICAL-STRUCTS) — each source error gets at most one `From` impl per target. +- TODO: Clarify the policy for canonical error structs (cf. [M-ERRORS-CANONICAL-STRUCTS](#M-ERRORS-CANONICAL-STRUCTS)) — each source error gets at most one `From` impl per target. - TODO: Provide a concrete bad example (every call site doing `.map_err(MyError::Io)?` for `std::io::Error`). - TODO: Provide a concrete good example (`impl From for MyError` once; call sites use `?` directly). -- TODO: Note interaction with M-ERRORS-CANONICAL-STRUCTS and M-APP-ERROR. +- TODO: Note interaction with [M-ERRORS-CANONICAL-STRUCTS](#M-ERRORS-CANONICAL-STRUCTS) and [M-APP-ERROR](../../apps/#M-APP-ERROR). diff --git a/src/guidelines/libs/ux/M-NO-PRELUDE.md b/src/guidelines/libs/ux/M-NO-PRELUDE.md index 57eb772..0b7d7c7 100644 --- a/src/guidelines/libs/ux/M-NO-PRELUDE.md +++ b/src/guidelines/libs/ux/M-NO-PRELUDE.md @@ -25,6 +25,6 @@ _ = Client::new(); // = note: ambiguous because of multiple glob imports of a name in the same module ``` -Preludes in particular do not resolve bad module design. If it looks like a prelude would make the crate easier to use or understand, this is almost always an indication that the existing module system needs restructuring, see M-BALANCED-MODULES. +Preludes in particular do not resolve bad module design. If it looks like a prelude would make the crate easier to use or understand, this is almost always an indication that the existing module system needs restructuring, see [M-BALANCED-MODULES](#M-BALANCED-MODULES). diff --git a/src/guidelines/libs/ux/M-PARAMETER-ORDER.md b/src/guidelines/libs/ux/M-PARAMETER-ORDER.md index 5cf8290..ea5fa90 100644 --- a/src/guidelines/libs/ux/M-PARAMETER-ORDER.md +++ b/src/guidelines/libs/ux/M-PARAMETER-ORDER.md @@ -12,4 +12,4 @@ Order function parameters from most to least important, and place closures (and - TODO: Specify the rule for multiple closures (e.g., `map_or_else(default, f)`) — does any closure count as "last", or only single-closure APIs? - TODO: Provide a concrete bad example (a function taking a closure followed by an integer count). - TODO: Provide a concrete good example (`fn retry(count: usize, f: impl FnMut() -> Result) -> ...`). -- TODO: Note interaction with M-PARAMETER-CONSISTENCY (which governs cross-crate consistency of the chosen order). +- TODO: Note interaction with [M-PARAMETER-CONSISTENCY](#M-PARAMETER-CONSISTENCY) (which governs cross-crate consistency of the chosen order). diff --git a/src/guidelines/performance/M-SHRINK-TO-FIT.md b/src/guidelines/performance/M-SHRINK-TO-FIT.md index 82126b4..d8e8e4a 100644 --- a/src/guidelines/performance/M-SHRINK-TO-FIT.md +++ b/src/guidelines/performance/M-SHRINK-TO-FIT.md @@ -5,7 +5,7 @@ To reduce memory footprint. 0.1 -Where large, long-lived, growable collections such as `Vec` or `String` were built without an exact size reservation (compare M-INITIAL-CAPACITY), the resulting collection should be shrunk via `shrink_to_fit` before storing it. +Where large, long-lived, growable collections such as `Vec` or `String` were built without an exact size reservation (compare [M-INITIAL-CAPACITY](#M-INITIAL-CAPACITY)), the resulting collection should be shrunk via `shrink_to_fit` before storing it. Rust's collections grow by powers of two when iteratively adding elements. In the worst case a collection might therefore use ~2x of its needed memory. @@ -19,4 +19,4 @@ for x in large_iter { // Good, frees up extra memory. long_lived.shrink_to_fit(); ``` -Note that this does not apply to conversions done via `into_boxed_*` and friends (compare M-BOX-DST), as these generally shrink before converting already. +Note that this does not apply to conversions done via `into_boxed_*` and friends (compare [M-BOX-DST](#M-BOX-DST)), as these generally shrink before converting already. diff --git a/src/guidelines/universal/M-LOG-NOT-PRINT.md b/src/guidelines/universal/M-LOG-NOT-PRINT.md index 60b2e6b..3e597a1 100644 --- a/src/guidelines/universal/M-LOG-NOT-PRINT.md +++ b/src/guidelines/universal/M-LOG-NOT-PRINT.md @@ -8,8 +8,8 @@ Production code paths should emit diagnostics through the project's telemetry framework (e.g., `tracing`, `log`) rather than via `println!`, `eprintln!`, `print!`, `eprint!`, or `dbg!`. Console output is reserved for CLI binaries that intentionally write to stdout/stderr as their user interface. - TODO: Enumerate the legitimate exceptions (CLI binaries' user-facing output, build scripts, examples, tests). -- TODO: Specify the recommended telemetry stack or refer to a separate decision (e.g., `tracing` with structured fields per M-LOG-STRUCTURED). +- TODO: Specify the recommended telemetry stack or refer to a separate decision (e.g., `tracing` with structured fields per [M-LOG-STRUCTURED](#M-LOG-STRUCTURED)). - TODO: Provide a concrete bad example (a library function calling `eprintln!("failed: {e}")` instead of `tracing::error!`). - TODO: Provide a concrete good example. - TODO: Note guidance for `dbg!` — banned in committed code; lint enforcement suggested. -- TODO: Note interaction with M-LOG-STRUCTURED. +- TODO: Note interaction with [M-LOG-STRUCTURED](#M-LOG-STRUCTURED). diff --git a/src/guidelines/universal/M-SHORT-NAMES.md b/src/guidelines/universal/M-SHORT-NAMES.md index d31f092..4d3f897 100644 --- a/src/guidelines/universal/M-SHORT-NAMES.md +++ b/src/guidelines/universal/M-SHORT-NAMES.md @@ -9,7 +9,7 @@ Identifiers for items (functions, methods, types, fields, modules) should stay s - TODO: Give a concrete length guideline or heuristic (e.g., prefer one or two words for methods on a type; avoid restating the type name in its methods). - TODO: Specify when longer names are warranted (rare public free functions where disambiguation is unavoidable, low-level safety-critical APIs). -- TODO: Clarify the relationship to M-WEASEL-WORDS (which targets weasel words) — this rule is about overall length, not specifically filler words. +- TODO: Clarify the relationship to [M-WEASEL-WORDS](#M-WEASEL-WORDS) (which targets weasel words) — this rule is about overall length, not specifically filler words. - TODO: Provide a concrete bad example (`UserService::get_user_by_id_from_database`). - TODO: Provide a concrete good example (`UserService::get(id)` or `Users::find(id)`). -- TODO: Note interaction with the Rust API Guidelines naming conventions and M-WEASEL-WORDS. +- TODO: Note interaction with the Rust API Guidelines naming conventions and [M-WEASEL-WORDS](#M-WEASEL-WORDS). From 9a15dfcf44b2938c2a46841d5f204c87713c9965 Mon Sep 17 00:00:00 2001 From: Ralf Biedert Date: Fri, 5 Jun 2026 18:23:30 +0200 Subject: [PATCH 09/10] Fix remaining TODOs. --- src/guidelines/checklist/README.md | 12 ++++---- .../libs/resilience/M-BUILD-RESULT.md | 25 ++++++++++++++++ .../libs/resilience/M-LOG-NOT-PRINT.md | 8 +++++ src/guidelines/libs/resilience/README.md | 2 ++ src/guidelines/libs/ux/M-ASYNC-FN.md | 22 +++++++++----- src/guidelines/libs/ux/M-BUILD-RESULT.md | 15 ---------- src/guidelines/libs/ux/M-COLLECTION-TRAITS.md | 20 ++++++++----- .../libs/ux/M-EXT-TRAITS-FOREIGN-ITEMS.md | 11 ------- src/guidelines/libs/ux/M-FROM-ERROR.md | 30 ++++++++++++++----- .../libs/ux/M-PARAMETER-CONSISTENCY.md | 28 ++++++++++++----- src/guidelines/libs/ux/M-PARAMETER-ORDER.md | 15 ---------- src/guidelines/libs/ux/README.md | 3 -- src/guidelines/universal/M-LOG-NOT-PRINT.md | 15 ---------- src/guidelines/universal/M-SHORT-NAMES.md | 15 +++++----- src/guidelines/universal/README.md | 1 - 15 files changed, 116 insertions(+), 106 deletions(-) create mode 100644 src/guidelines/libs/resilience/M-BUILD-RESULT.md create mode 100644 src/guidelines/libs/resilience/M-LOG-NOT-PRINT.md delete mode 100644 src/guidelines/libs/ux/M-BUILD-RESULT.md delete mode 100644 src/guidelines/libs/ux/M-EXT-TRAITS-FOREIGN-ITEMS.md delete mode 100644 src/guidelines/libs/ux/M-PARAMETER-ORDER.md delete mode 100644 src/guidelines/universal/M-LOG-NOT-PRINT.md diff --git a/src/guidelines/checklist/README.md b/src/guidelines/checklist/README.md index 32ae890..7298826 100644 --- a/src/guidelines/checklist/README.md +++ b/src/guidelines/checklist/README.md @@ -16,7 +16,6 @@ - [ ] Detected programming bugs are panics, not errors ([M-PANIC-ON-BUG]) - [ ] Magic values are documented ([M-DOCUMENTED-MAGIC]) - [ ] Use structured logging with message templates ([M-LOG-STRUCTURED]) - - [ ] Production code uses telemetry, not println ([M-LOG-NOT-PRINT]) - **Library / Interoperability** - [ ] Types are Send ([M-TYPES-SEND]) - [ ] Native escape hatches ([M-ESCAPE-HATCHES]) @@ -29,18 +28,15 @@ - [ ] Errors are canonical structs ([M-ERRORS-CANONICAL-STRUCTS]) - [ ] Canonical error conversion uses `From`, not `map_err` ([M-FROM-ERROR]) - [ ] Complex type construction has builders ([M-INIT-BUILDER]) - - [ ] Builders validate in final `.build()` ([M-BUILD-RESULT]) - [ ] Complex type initialization hierarchies are cascaded ([M-INIT-CASCADED]) - [ ] Services are Clone ([M-SERVICES-CLONE]) - [ ] Accept `impl AsRef<>` where feasible ([M-IMPL-ASREF]) - [ ] Accept `impl RangeBounds<>` where feasible ([M-IMPL-RANGEBOUNDS]) - [ ] Accept `impl 'IO'` where feasible ('sans IO') ([M-IMPL-IO]) - [ ] Essential functionality should be inherent ([M-ESSENTIAL-FN-INHERENT]) - - [ ] Extension traits are reserved for foreign items ([M-EXT-TRAITS-FOREIGN-ITEMS]) - [ ] Modules are balanced in size and scope ([M-BALANCED-MODULES]) - [ ] Don't define preludes ([M-NO-PRELUDE]) - - [ ] Parameter ordering is consistent across crates or ecosystem ([M-PARAMETER-CONSISTENCY]) - - [ ] Important parameters go first, closures last ([M-PARAMETER-ORDER]) + - [ ] Parameter ordering is consistent ([M-PARAMETER-CONSISTENCY]) - [ ] Collections implement the appropriate iter traits ([M-COLLECTION-TRAITS]) - [ ] Functions are `async` over returning a Future ([M-ASYNC-FN]) - **Library / Resilience** @@ -49,10 +45,12 @@ - [ ] Integration tests live under `tests/` ([M-INTEGRATION-TESTS]) - [ ] Use the proper type family ([M-STRONG-TYPES]) - [ ] Newtypes guard their invariants ([M-STRONG-TYPES-GUARD]) + - [ ] Builders validate in final `.build()` ([M-BUILD-RESULT]) - [ ] Don't glob re-export items ([M-NO-GLOB-REEXPORTS]) - [ ] Avoid statics ([M-AVOID-STATICS]) - [ ] Panic continuation is last resort ([M-PANIC-CONTINUATION]) - [ ] Custom panics have a helpful message ([M-PANIC-MESSAGE]) + - [ ] Production code uses telemetry, not println ([M-LOG-NOT-PRINT]) - **Library / Building** - [ ] Libraries work out of the box ([M-OOBE]) - [ ] Native `-sys` crates compile without dependencies ([M-SYS-CRATES]) @@ -123,7 +121,7 @@ [M-PANIC-MESSAGE]: ../libs/resilience/#M-PANIC-MESSAGE [M-DOCUMENTED-MAGIC]: ../universal/#M-DOCUMENTED-MAGIC [M-LOG-STRUCTURED]: ../universal/#M-LOG-STRUCTURED -[M-LOG-NOT-PRINT]: ../universal/#M-LOG-NOT-PRINT +[M-LOG-NOT-PRINT]: ../libs/resilience/#M-LOG-NOT-PRINT [M-TYPES-SEND]: ../libs/interop/#M-TYPES-SEND @@ -141,7 +139,7 @@ [M-ERRORS-CANONICAL-STRUCTS]: ../libs/ux/#M-ERRORS-CANONICAL-STRUCTS [M-FROM-ERROR]: ../libs/ux/#M-FROM-ERROR [M-INIT-BUILDER]: ../libs/ux/#M-INIT-BUILDER -[M-BUILD-RESULT]: ../libs/ux/#M-BUILD-RESULT +[M-BUILD-RESULT]: ../libs/resilience/#M-BUILD-RESULT [M-INIT-CASCADED]: ../libs/ux/#M-INIT-CASCADED [M-SERVICES-CLONE]: ../libs/ux/#M-SERVICES-CLONE [M-IMPL-ASREF]: ../libs/ux/#M-IMPL-ASREF diff --git a/src/guidelines/libs/resilience/M-BUILD-RESULT.md b/src/guidelines/libs/resilience/M-BUILD-RESULT.md new file mode 100644 index 0000000..78e501a --- /dev/null +++ b/src/guidelines/libs/resilience/M-BUILD-RESULT.md @@ -0,0 +1,25 @@ + + +## Builders validate in final `.build()` (M-BUILD-RESULT) { #M-BUILD-RESULT } + +To de-noise error builder usage. +0.1 + +A builder's per-field setters should accept input without failing, final validation should be done by `.build()`. + +Fallible setters add noise, and still don't guard against interdependent error conditions. Where builders are fallible they should offer a `Result`-carrying `.build()` instead. + +```rust +// Bad, forces repeated error checks that provide no value. +Foo::builder() + .name("Foo")? + .distance(42)? + .build(); + +// Good, consolidates sanity checking and allows for cross-checks +// between properties. +Foo::builder() + .name("Foo") + .distance(42) + .build()?; +``` diff --git a/src/guidelines/libs/resilience/M-LOG-NOT-PRINT.md b/src/guidelines/libs/resilience/M-LOG-NOT-PRINT.md new file mode 100644 index 0000000..680f851 --- /dev/null +++ b/src/guidelines/libs/resilience/M-LOG-NOT-PRINT.md @@ -0,0 +1,8 @@ + + +## Production code uses telemetry, not println (M-LOG-NOT-PRINT) { #M-LOG-NOT-PRINT } + +To ensure diagnostics are available where they need to be. +0.1 + +Production code paths should emit diagnostics through the project's telemetry framework rather than via `println!` or `dbg!`. Console output is reserved for CLIs that intentionally write to stdout as their user interface. diff --git a/src/guidelines/libs/resilience/README.md b/src/guidelines/libs/resilience/README.md index 5ce480d..eea61dd 100644 --- a/src/guidelines/libs/resilience/README.md +++ b/src/guidelines/libs/resilience/README.md @@ -7,7 +7,9 @@ {{#include M-INTEGRATION-TESTS.md}} {{#include M-STRONG-TYPES.md}} {{#include M-STRONG-TYPES-GUARD.md}} +{{#include M-BUILD-RESULT.md}} {{#include M-NO-GLOB-REEXPORTS.md}} {{#include M-AVOID-STATICS.md}} {{#include M-PANIC-CONTINUATION.md}} {{#include M-PANIC-MESSAGE.md}} +{{#include M-LOG-NOT-PRINT.md}} diff --git a/src/guidelines/libs/ux/M-ASYNC-FN.md b/src/guidelines/libs/ux/M-ASYNC-FN.md index b6b4872..d9b4598 100644 --- a/src/guidelines/libs/ux/M-ASYNC-FN.md +++ b/src/guidelines/libs/ux/M-ASYNC-FN.md @@ -1,14 +1,20 @@ -## Where possible functions are `async` over returning a Future (M-ASYNC-FN) { #M-ASYNC-FN } +## Functions are `async` over returning a Future (M-ASYNC-FN) { #M-ASYNC-FN } -An `async fn` signature is shorter, infers lifetimes correctly by default, and reads as ordinary control flow; hand-written `-> impl Future` returns add noise, frequently require explicit `+ '_` / `+ Send` bounds, and are easier to get subtly wrong. +To simplify code and easier to understand APIs. 0.1 -Prefer writing `async fn foo(...) -> T` over `fn foo(...) -> impl Future` (or a boxed future) when both are viable. Fall back to an explicit `Future`-returning signature only when the function genuinely cannot be `async` — for example, when extra `Send`/`Sync`/`'static` bounds, manual lifetime control, or returning a stored/boxed future is required. +Functions should be declared `async fn foo()` over `fn foo() -> impl Future` when both are viable. -- TODO: Enumerate the legitimate reasons to write a non-`async` future-returning signature (e.g., trait methods pre-`async fn in trait` stabilization, manually pinned futures, explicit `Send` bounds on the returned future, returning a `BoxFuture` for object safety). -- TODO: Clarify the rule for trait methods (use `async fn in trait` where available; document any MSRV constraints). -- TODO: Provide a concrete bad example (`fn load(&self) -> impl Future> + '_ { async move { ... } }`). -- TODO: Provide a concrete good example (`async fn load(&self) -> Result { ... }`). -- TODO: Note interaction with M-IMPL-IO, M-SERVICES-CLONE, and any project-wide `Send`-bound conventions. +Functions marked `async` are more idiomatic and easier to read. An explicit `Future`-returning signature should only be used when required, for example inside traits. + +```rust +impl Foo { + // Bad, signature is noisier and the body needs an extra `async` block + fn foo() -> impl Future> { async { Ok(t) } } + + // Good, method and implementation reads normally + async fn foo() -> Result { Ok(t) } +} +``` diff --git a/src/guidelines/libs/ux/M-BUILD-RESULT.md b/src/guidelines/libs/ux/M-BUILD-RESULT.md deleted file mode 100644 index 7641938..0000000 --- a/src/guidelines/libs/ux/M-BUILD-RESULT.md +++ /dev/null @@ -1,15 +0,0 @@ - - -## Builders validate in final `.build()` (M-BUILD-RESULT) { #M-BUILD-RESULT } - -Concentrating validation in the terminal `.build()` call gives users a single, predictable place where invalid configurations are reported, lets individual setter methods stay infallible and chainable, and makes the success type of the builder unambiguous. -0.1 - -A builder's per-field setter methods should accept input without failing. All cross-field validation, required-field checks, and other consistency rules belong in the final `.build()` method, which returns a `Result` (or equivalent) carrying any error. - -- TODO: State the expected `.build()` signature (e.g., `fn build(self) -> Result` vs. infallible `fn build(self) -> T`) and when each is appropriate. -- TODO: Clarify whether setters may ever return `Result` (e.g., for parsing-style inputs) or whether they must always be infallible. -- TODO: Specify how errors should aggregate (single error vs. collected errors for multiple problems). -- TODO: Provide a concrete bad example (a setter that returns `Result`, or validation scattered across setters). -- TODO: Provide a concrete good example (infallible chainable setters; `.build()` returns `Result` with a canonical error type per [M-ERRORS-CANONICAL-STRUCTS](#M-ERRORS-CANONICAL-STRUCTS)). -- TODO: Note interaction with [M-INIT-BUILDER](#M-INIT-BUILDER) and [M-INIT-CASCADED](#M-INIT-CASCADED). diff --git a/src/guidelines/libs/ux/M-COLLECTION-TRAITS.md b/src/guidelines/libs/ux/M-COLLECTION-TRAITS.md index 4a117d8..43f93ee 100644 --- a/src/guidelines/libs/ux/M-COLLECTION-TRAITS.md +++ b/src/guidelines/libs/ux/M-COLLECTION-TRAITS.md @@ -2,15 +2,19 @@ ## Collections implement the appropriate iter traits (M-COLLECTION-TRAITS) { #M-COLLECTION-TRAITS } -Implementing the standard iterator traits lets custom collections drop into `for` loops, `collect`, and iterator chains the same way `Vec` and `HashMap` do; missing them forces users into ad-hoc workarounds and breaks ecosystem composition. +To ensure collections compose. 0.1 -Custom collection types should implement the iterator-facing traits the standard library uses — at minimum `IntoIterator` for the owned type as well as for `&Collection` and `&mut Collection`, and `FromIterator` / `Extend` where construction or accumulation makes sense. +Custom collections should implement the iterator-facing traits the standard library offers. -- TODO: Enumerate the exact set of required traits (`IntoIterator` on three forms, `FromIterator`, `Extend`) and which are optional vs. recommended. -- TODO: Specify the conventional inherent methods that should accompany them (`iter`, `iter_mut`, `into_iter`, `len`, `is_empty`). -- TODO: Note when *not* to implement a given trait (e.g., `FromIterator` for collections that need extra context to construct). -- TODO: Provide a concrete bad example (a custom collection missing `IntoIterator for &Collection` so users cannot iterate by reference in a `for` loop). -- TODO: Provide a concrete good example. -- TODO: Note interaction with [M-ESSENTIAL-FN-INHERENT](#M-ESSENTIAL-FN-INHERENT) and [M-IMPL-ASREF](#M-IMPL-ASREF). +Whenever you define a new collection type `Collection` for consumption by third parties, the following traits and types should also be implemented, [see here](https://cheats.rs/#iterators) for more details: +- the structs `IntoIter`, `Iter` and `IterMut`, +- an `impl Iterator` for all of them, +- the methods `c.iter()` and `c.iter_mut()`, +- an `impl IntoIterator` for `Collection`, `&Collection` and `&mut Collection`, +- an `impl FromIterator` for `Collection`, +- an `Extend` for `Collection`, +- `DoubleEndedIterator`, `ExactSizeIterator`, ... as applicable + +In addition, make sure you implement `size_hint()` on all iterators and do so truthfully. diff --git a/src/guidelines/libs/ux/M-EXT-TRAITS-FOREIGN-ITEMS.md b/src/guidelines/libs/ux/M-EXT-TRAITS-FOREIGN-ITEMS.md deleted file mode 100644 index aa72a78..0000000 --- a/src/guidelines/libs/ux/M-EXT-TRAITS-FOREIGN-ITEMS.md +++ /dev/null @@ -1,11 +0,0 @@ - - -## Extension traits are reserved for foreign items (M-EXT-TRAITS-FOREIGN-ITEMS) { #M-EXT-TRAITS-FOREIGN-ITEMS } - -Extension traits add API surface and import friction; they are only justified when inherent methods or owned traits aren't possible because the target type is foreign. -0.1 - -- TODO: Define what counts as an "extension trait" (e.g., a trait whose primary purpose is to add methods to a type owned by another crate via `impl Ext for ForeignType`). -- TODO: Specify when extension traits are acceptable (foreign types from `std` or third-party crates) vs. when they must not be used (types owned by the current crate — use inherent impls or a regular trait instead). -- TODO: Clarify naming, sealing, and visibility expectations for such traits. -- TODO: Provide good/bad examples. diff --git a/src/guidelines/libs/ux/M-FROM-ERROR.md b/src/guidelines/libs/ux/M-FROM-ERROR.md index d3f1a07..2fa3216 100644 --- a/src/guidelines/libs/ux/M-FROM-ERROR.md +++ b/src/guidelines/libs/ux/M-FROM-ERROR.md @@ -2,13 +2,29 @@ ## Canonical error conversion uses `From`, not `map_err` (M-FROM-ERROR) { #M-FROM-ERROR } -When `From` is implemented for the function's error type, the `?` operator converts automatically; sprinkling `.map_err(...)` at call sites duplicates that mapping, hides it from review, and lets variants drift as new conversions are added in different places. +To ensure idiomatic error handling. 0.1 -Conversions between error types that are part of the project's canonical error hierarchy should be implemented as `impl From for TargetError` (typically via `#[from]` on a `thiserror`-style derive or an explicit impl) and used implicitly via `?`. Call sites should not reach for `.map_err(...)` to perform the same conversion repeatedly. +Where an `Error` type is owned, it should `impl From for Error {}` instead of handling the conversion throughout the code via `.map_error()`. Calling `.map_error()` is only appropriate when dealing with foreign error types, or if contextual information needs to be preserved. -- TODO: Specify when `map_err` is still appropriate (one-off context attachment, lossy summarization, conversions that depend on local context the `From` impl cannot see). -- TODO: Clarify the policy for canonical error structs (cf. [M-ERRORS-CANONICAL-STRUCTS](#M-ERRORS-CANONICAL-STRUCTS)) — each source error gets at most one `From` impl per target. -- TODO: Provide a concrete bad example (every call site doing `.map_err(MyError::Io)?` for `std::io::Error`). -- TODO: Provide a concrete good example (`impl From for MyError` once; call sites use `?` directly). -- TODO: Note interaction with [M-ERRORS-CANONICAL-STRUCTS](#M-ERRORS-CANONICAL-STRUCTS) and [M-APP-ERROR](../../apps/#M-APP-ERROR). +```rust +// Bad, repeats the same conversion at every call site and obscures the happy path. +fn load() -> Result { + let bytes = read("config.toml").map_err(|e| MyError::Io(e))?; + let text = str::from_utf8(&bytes).map_err(|e| MyError::Utf8(e))?; + let cfg = toml::from_str(text).map_err(|e| MyError::Parse(e))?; + Ok(cfg) +} + +// Good, define the conversion once and let `?` apply it. +impl From for MyError { ... } +impl From for MyError { ... } +impl From for MyError { ... } + +fn load() -> Result { + let bytes = read("config.toml")?; + let text = str::from_utf8(&bytes)?; + let cfg = toml::from_str(text)?; + Ok(cfg) +} +``` diff --git a/src/guidelines/libs/ux/M-PARAMETER-CONSISTENCY.md b/src/guidelines/libs/ux/M-PARAMETER-CONSISTENCY.md index 412ff24..a7816e0 100644 --- a/src/guidelines/libs/ux/M-PARAMETER-CONSISTENCY.md +++ b/src/guidelines/libs/ux/M-PARAMETER-CONSISTENCY.md @@ -1,14 +1,26 @@ -## Parameter ordering is consistent across crates or ecosystem (M-PARAMETER-CONSISTENCY) { #M-PARAMETER-CONSISTENCY } +## Parameter ordering is consistent (M-PARAMETER-CONSISTENCY) { #M-PARAMETER-CONSISTENCY } -Consistent parameter order across related APIs reduces cognitive load, prevents argument-swap bugs, and makes it easier to learn and remember a family of functions. +To reduce development friction. 0.1 -When the same conceptual parameters appear in multiple functions — within a crate or across crates in the same ecosystem — they should appear in the same order everywhere. +When the same conceptual parameters appear in multiple functions (within a crate or across crates in the same ecosystem), they should appear in the same order everywhere: -- TODO: Define the precedence when conventions conflict (own crate vs. broader ecosystem vs. `std`). -- TODO: List recurring parameter pairs that need a canonical order (e.g., `src, dst` vs `dst, src`; `key, value`; `haystack, needle`; `expected, actual`). -- TODO: Provide a concrete bad example (two sibling functions with swapped argument order). -- TODO: Provide a concrete good example. -- TODO: Clarify whether this also constrains builder method order, trait method order, or only free/inherent functions. +- important or call-specific parameters should generally go first, +- ubiquitous parameters rather go last (e.g., `&logger`), +- closures always go last (functions should not accept more than one closure). + +```rust +// Bad, the order of `user_id` and `tenant_id` flips between functions, and +// the logger sometimes appears first, sometimes last. +fn create_user(logger: &Logger, user_id: UserId, tenant_id: TenantId) -> Result<()> { ... } +fn delete_user(tenant_id: TenantId, user_id: UserId, logger: &Logger) -> Result<()> { ... } +fn rename_user(user_id: UserId, new_name: &str, tenant_id: TenantId, logger: &Logger) -> Result<()> { ... } + +// Good, call-specific parameters first in a consistent order, ubiquitous +// `logger` always last. +fn create_user(tenant_id: TenantId, user_id: UserId, logger: &Logger) -> Result<()> { ... } +fn delete_user(tenant_id: TenantId, user_id: UserId, logger: &Logger) -> Result<()> { ... } +fn rename_user(tenant_id: TenantId, user_id: UserId, new_name: &str, logger: &Logger) -> Result<()> { ... } +``` diff --git a/src/guidelines/libs/ux/M-PARAMETER-ORDER.md b/src/guidelines/libs/ux/M-PARAMETER-ORDER.md deleted file mode 100644 index ea5fa90..0000000 --- a/src/guidelines/libs/ux/M-PARAMETER-ORDER.md +++ /dev/null @@ -1,15 +0,0 @@ - - -## Important parameters go first, closures last (M-PARAMETER-ORDER) { #M-PARAMETER-ORDER } - -A predictable parameter order keeps the most relevant arguments visible at the call site and avoids the awkward formatting that occurs when a long closure precedes plain arguments; following this convention also makes APIs scan-readable across a crate. -0.1 - -Order function parameters from most to least important, and place closures (and other large/inline-defined arguments such as `impl FnMut`, `impl Fn`, builder lambdas) at the end of the signature. - -- TODO: Define "importance" concretely (e.g., the conceptual subject of the operation comes first; configuration knobs follow; optional/contextual data later). -- TODO: Clarify how this interacts with methods that already have a `self` receiver (the receiver is always first; the rule applies to the remaining parameters). -- TODO: Specify the rule for multiple closures (e.g., `map_or_else(default, f)`) — does any closure count as "last", or only single-closure APIs? -- TODO: Provide a concrete bad example (a function taking a closure followed by an integer count). -- TODO: Provide a concrete good example (`fn retry(count: usize, f: impl FnMut() -> Result) -> ...`). -- TODO: Note interaction with [M-PARAMETER-CONSISTENCY](#M-PARAMETER-CONSISTENCY) (which governs cross-crate consistency of the chosen order). diff --git a/src/guidelines/libs/ux/README.md b/src/guidelines/libs/ux/README.md index 02a4acd..4e80444 100644 --- a/src/guidelines/libs/ux/README.md +++ b/src/guidelines/libs/ux/README.md @@ -8,17 +8,14 @@ {{#include M-ERRORS-CANONICAL-STRUCTS.md}} {{#include M-FROM-ERROR.md}} {{#include M-INIT-BUILDER.md}} -{{#include M-BUILD-RESULT.md}} {{#include M-INIT-CASCADED.md}} {{#include M-SERVICES-CLONE.md}} {{#include M-IMPL-ASREF.md}} {{#include M-IMPL-RANGEBOUNDS.md}} {{#include M-IMPL-IO.md}} {{#include M-ESSENTIAL-FN-INHERENT.md}} -{{#include M-EXT-TRAITS-FOREIGN-ITEMS.md}} {{#include M-BALANCED-MODULES.md}} {{#include M-NO-PRELUDE.md}} {{#include M-PARAMETER-CONSISTENCY.md}} -{{#include M-PARAMETER-ORDER.md}} {{#include M-COLLECTION-TRAITS.md}} {{#include M-ASYNC-FN.md}} diff --git a/src/guidelines/universal/M-LOG-NOT-PRINT.md b/src/guidelines/universal/M-LOG-NOT-PRINT.md deleted file mode 100644 index 3e597a1..0000000 --- a/src/guidelines/universal/M-LOG-NOT-PRINT.md +++ /dev/null @@ -1,15 +0,0 @@ - - -## Production code uses telemetry, not println (M-LOG-NOT-PRINT) { #M-LOG-NOT-PRINT } - -`println!` / `eprintln!` / `dbg!` bypass log levels, structured fields, sampling, sinks, and filters; they pollute stdout/stderr in ways that are invisible to telemetry pipelines and uncontrollable in production. -0.1 - -Production code paths should emit diagnostics through the project's telemetry framework (e.g., `tracing`, `log`) rather than via `println!`, `eprintln!`, `print!`, `eprint!`, or `dbg!`. Console output is reserved for CLI binaries that intentionally write to stdout/stderr as their user interface. - -- TODO: Enumerate the legitimate exceptions (CLI binaries' user-facing output, build scripts, examples, tests). -- TODO: Specify the recommended telemetry stack or refer to a separate decision (e.g., `tracing` with structured fields per [M-LOG-STRUCTURED](#M-LOG-STRUCTURED)). -- TODO: Provide a concrete bad example (a library function calling `eprintln!("failed: {e}")` instead of `tracing::error!`). -- TODO: Provide a concrete good example. -- TODO: Note guidance for `dbg!` — banned in committed code; lint enforcement suggested. -- TODO: Note interaction with [M-LOG-STRUCTURED](#M-LOG-STRUCTURED). diff --git a/src/guidelines/universal/M-SHORT-NAMES.md b/src/guidelines/universal/M-SHORT-NAMES.md index 4d3f897..267ce0a 100644 --- a/src/guidelines/universal/M-SHORT-NAMES.md +++ b/src/guidelines/universal/M-SHORT-NAMES.md @@ -2,14 +2,13 @@ ## Names of items are short (M-SHORT-NAMES) { #M-SHORT-NAMES } -Short names read faster, fit on one line at call sites, and discourage smuggling implementation detail or hedge words into identifiers; the surrounding type and module context usually carries the rest of the meaning. +To make Rust code idiomatic. 0.1 -Identifiers for items (functions, methods, types, fields, modules) should stay short, leaning on context — the enclosing module, type, or trait — to disambiguate rather than encoding it into the name itself. +The Rust convention that item identifiers are short should be followed: -- TODO: Give a concrete length guideline or heuristic (e.g., prefer one or two words for methods on a type; avoid restating the type name in its methods). -- TODO: Specify when longer names are warranted (rare public free functions where disambiguation is unavoidable, low-level safety-critical APIs). -- TODO: Clarify the relationship to [M-WEASEL-WORDS](#M-WEASEL-WORDS) (which targets weasel words) — this rule is about overall length, not specifically filler words. -- TODO: Provide a concrete bad example (`UserService::get_user_by_id_from_database`). -- TODO: Provide a concrete good example (`UserService::get(id)` or `Users::find(id)`). -- TODO: Note interaction with the Rust API Guidelines naming conventions and [M-WEASEL-WORDS](#M-WEASEL-WORDS). +- identifiers should not compound more than 2 short words (`AppConfig` over `GlobalApplicationConfig`), +- module or crate information shouldn't be baked into prefixes (`foo::Id` over `foo::FooId`), in particular when the direct 'super' item is sufficiently descriptive - in these cases users are expected to disambiguate items locally via qualifiers where needed (`fn convert(foo::Id) -> bar::Id`). +- abbreviations are preferred (`CallbackFn` over `CallbackFunction`), + +Any of these rules can be broken where it makes local sense, but on a per-crate bases these exceptions should be _exceptional_ and well motivated. diff --git a/src/guidelines/universal/README.md b/src/guidelines/universal/README.md index 8ee9ddc..8e9513e 100644 --- a/src/guidelines/universal/README.md +++ b/src/guidelines/universal/README.md @@ -15,4 +15,3 @@ {{#include M-PANIC-ON-BUG.md}} {{#include M-DOCUMENTED-MAGIC.md}} {{#include M-LOG-STRUCTURED.md}} -{{#include M-LOG-NOT-PRINT.md}} From b7af8215512f7b70f6b7cb6290c1bc98c5eb5ca6 Mon Sep 17 00:00:00 2001 From: Ralf Biedert Date: Mon, 15 Jun 2026 18:04:44 +0200 Subject: [PATCH 10/10] Integrate feedback. --- added-guidelines.md | 45 +++++++++++ .../ai/M-NO-META-DESIGN-DOCUMENTATION.md | 2 +- src/guidelines/ai/M-SINGLE-ITEM-PATH.md | 4 +- src/guidelines/ai/M-TAUTOLOGICAL-TESTS.md | 2 + src/guidelines/apps/M-TARGET-CPU.md | 5 ++ src/guidelines/checklist/README.md | 4 + src/guidelines/ffi/M-FFI-NAMING.md | 2 +- .../libs/resilience/M-BUILD-RESULT.md | 2 + .../resilience/M-INTEGRATION-TEST-UTILS.md | 13 ++++ .../libs/resilience/M-INTEGRATION-TESTS.md | 2 +- .../libs/resilience/M-PANIC-MESSAGE.md | 4 + .../libs/resilience/M-STRONG-TYPES-GUARD.md | 7 +- src/guidelines/libs/resilience/README.md | 1 + src/guidelines/libs/ux/M-ASYNC-FN.md | 2 +- src/guidelines/macros/M-MACRO-MAIN-CRATE.md | 4 +- src/guidelines/macros/M-MACROS-DONT-LIE.md | 2 +- .../performance/M-ASYNC-STACK-SIZE.md | 77 +++++++++++++++++++ src/guidelines/performance/M-FAST-HASHER.md | 7 +- src/guidelines/performance/M-SHRINK-TO-FIT.md | 2 +- src/guidelines/performance/README.md | 1 + 20 files changed, 175 insertions(+), 13 deletions(-) create mode 100644 added-guidelines.md create mode 100644 src/guidelines/libs/resilience/M-INTEGRATION-TEST-UTILS.md create mode 100644 src/guidelines/performance/M-ASYNC-STACK-SIZE.md diff --git a/added-guidelines.md b/added-guidelines.md new file mode 100644 index 0000000..c87f216 --- /dev/null +++ b/added-guidelines.md @@ -0,0 +1,45 @@ +# Guidelines added on this branch + +| Name | Text | +|---|---| +| [M-ASYNC-FN](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/ux/M-ASYNC-FN.md) | Functions are `async` over returning a Future | +| [M-AVOID-INDIRECTION](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/performance/M-AVOID-INDIRECTION.md) | Nested type hierarchies should avoid needless indirection | +| [M-BALANCED-MODULES](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/ux/M-BALANCED-MODULES.md) | Modules are balanced in size and scope | +| [M-BOX-DST](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/performance/M-BOX-DST.md) | Use boxed slices and strings for immutable owned sequences | +| [M-BUILD-RESULT](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/resilience/M-BUILD-RESULT.md) | Builders validate in final `.build()` | +| [M-CARGO-WORKSPACE](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/project/M-CARGO-WORKSPACE.md) | Common settings come from the workspace Cargo.toml | +| [M-COLLECTION-TRAITS](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/ux/M-COLLECTION-TRAITS.md) | Collections implement the appropriate iter traits | +| [M-CRATES-FLAT-FOLDER](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/project/M-CRATES-FLAT-FOLDER.md) | All crates are siblings in one folder | +| [M-CRATES-IN-WORKSPACE](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/project/M-CRATES-IN-WORKSPACE.md) | The workspace lists and versions all crates | +| [M-FAST-HASHER](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/performance/M-FAST-HASHER.md) | Use a fast hasher where possible | +| [M-FFI-NAMING](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/ffi/M-FFI-NAMING.md) | FFI crates follow established naming conventions | +| [M-FFI-TRANSLATES](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/ffi/M-FFI-TRANSLATES.md) | Business logic belongs in core crates, FFI only translates | +| [M-FOREIGN-REEXPORTS](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/interop/M-FOREIGN-REEXPORTS.md) | Items come from their original crate | +| [M-FROM-ERROR](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/ux/M-FROM-ERROR.md) | Canonical error conversion uses `From`, not `map_err` | +| [M-HUMAN-REVIEW](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/ai/M-HUMAN-REVIEW.md) | All agent-generated APIs require human review | +| [M-INITIAL-CAPACITY](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/performance/M-INITIAL-CAPACITY.md) | Collections are created with sufficient initial capacity | +| [M-INTEGRATION-TESTS](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/resilience/M-INTEGRATION-TESTS.md) | Integration tests live under `tests/` | +| [M-LATEST-EDITION](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/project/M-LATEST-EDITION.md) | New crates target latest edition | +| [M-LOG-NOT-PRINT](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/resilience/M-LOG-NOT-PRINT.md) | Production code uses telemetry, not println | +| [M-LOG-OVERHEAD](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/performance/M-LOG-OVERHEAD.md) | Library telemetry does not tank performance | +| [M-MACRO-HELPERS](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/macros/M-MACRO-HELPERS.md) | Third party items come from hidden `_private` module | +| [M-MACRO-LAST-RESORT](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/macros/M-MACRO-LAST-RESORT.md) | Macros are a last resort | +| [M-MACRO-MAIN-CRATE](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/macros/M-MACRO-MAIN-CRATE.md) | Macros assume main crate | +| [M-MACROS-DONT-LIE](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/macros/M-MACROS-DONT-LIE.md) | Macros don't lie about signatures | +| [M-MBE-OVER-PROC](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/macros/M-MBE-OVER-PROC.md) | Prefer 'macros by example' over proc macros | +| [M-MEM-REUSE](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/performance/M-MEM-REUSE.md) | Reuse allocations where possible | +| [M-MSRV](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/project/M-MSRV.md) | MSRV is conservatively updated | +| [M-NO-META-DESIGN-DOCUMENTATION](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/ai/M-NO-META-DESIGN-DOCUMENTATION.md) | Avoid meta design documentation | +| [M-NO-PRELUDE](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/ux/M-NO-PRELUDE.md) | Don't define preludes | +| [M-PANIC-CONTINUATION](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/resilience/M-PANIC-CONTINUATION.md) | Panic continuation is last resort | +| [M-PANIC-MESSAGE](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/resilience/M-PANIC-MESSAGE.md) | Custom panics have a helpful message | +| [M-PARAMETER-CONSISTENCY](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/ux/M-PARAMETER-CONSISTENCY.md) | Parameter ordering is consistent | +| [M-PROC-IMPL](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/macros/M-PROC-IMPL.md) | Proc macros should have separate impl crate incl. tests | +| [M-PROC-IMPLIED-ITEMS](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/macros/M-PROC-IMPLIED-ITEMS.md) | Proc macros don't produce implied or hidden items | +| [M-RUST-SHAPED](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/ai/M-RUST-SHAPED.md) | Rust code solves Rust problems | +| [M-SHORT-NAMES](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/universal/M-SHORT-NAMES.md) | Names of items are short | +| [M-SHRINK-TO-FIT](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/performance/M-SHRINK-TO-FIT.md) | Shrink collections to fit after building | +| [M-SINGLE-ITEM-PATH](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/ai/M-SINGLE-ITEM-PATH.md) | Items are only visible through one path | +| [M-STRONG-TYPES-GUARD](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/libs/resilience/M-STRONG-TYPES-GUARD.md) | Newtypes guard their invariants | +| [M-TARGET-CPU](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/apps/M-TARGET-CPU.md) | Applications target highest viable target-cpu | +| [M-TAUTOLOGICAL-TESTS](https://github.com/microsoft/rust-guidelines/blob/u/ralfbiedert/2026-05-update/src/guidelines/ai/M-TAUTOLOGICAL-TESTS.md) | Tests do not assert ground truth | diff --git a/src/guidelines/ai/M-NO-META-DESIGN-DOCUMENTATION.md b/src/guidelines/ai/M-NO-META-DESIGN-DOCUMENTATION.md index 32511a5..cd116b1 100644 --- a/src/guidelines/ai/M-NO-META-DESIGN-DOCUMENTATION.md +++ b/src/guidelines/ai/M-NO-META-DESIGN-DOCUMENTATION.md @@ -5,7 +5,7 @@ to avoid confusing users with information not relevant to them. 0.1 -Crate and module documentation must be free of meta design narratives that were only relevant during the creation of a crate. +Crate and module documentation must be free of meta design narratives that were only relevant during the creation of a crate. In other words, it is the end-state that is to be documented, not the design journey. Agents frequently produce sections that describe how a change was designed, "why we picked X over Y" essays, and design journals inside user-facing documentation. These artifacts might be interesting diagnostics while working on the project, but they are mostly meaningless to end users. diff --git a/src/guidelines/ai/M-SINGLE-ITEM-PATH.md b/src/guidelines/ai/M-SINGLE-ITEM-PATH.md index ff6ecc5..00ab955 100644 --- a/src/guidelines/ai/M-SINGLE-ITEM-PATH.md +++ b/src/guidelines/ai/M-SINGLE-ITEM-PATH.md @@ -29,4 +29,6 @@ pub(crate) mod db { pub use db::Connection; ``` -Similarly, re-exports of foreign items are not covered by this rule, although they should follow [M-FOREIGN-REEXPORTS](../libs/interop/#M-FOREIGN-REEXPORTS). +Similarly, re-exports of foreign items are not covered by this rule, although they should follow [M-FOREIGN-REEXPORTS](../libs/interop/#M-FOREIGN-REEXPORTS). + +Likewise, this rule also does not apply to public-but-hidden `_private` modules needed by macros, compare [M-MACRO-HELPERS](../macros/#M-MACRO-HELPERS). diff --git a/src/guidelines/ai/M-TAUTOLOGICAL-TESTS.md b/src/guidelines/ai/M-TAUTOLOGICAL-TESTS.md index c26905f..1282ace 100644 --- a/src/guidelines/ai/M-TAUTOLOGICAL-TESTS.md +++ b/src/guidelines/ai/M-TAUTOLOGICAL-TESTS.md @@ -18,4 +18,6 @@ fn checkpoints_are_correct() { } ``` +Where these are used to satisfy mutation tests, the mutation test should be skipped instead. + Instead, a meaningful test would check a property the constants are supposed to satisfy, for example that they are evenly spaced, monotonically increasing, or impose some direction in related logic. diff --git a/src/guidelines/apps/M-TARGET-CPU.md b/src/guidelines/apps/M-TARGET-CPU.md index 3994493..f6adf14 100644 --- a/src/guidelines/apps/M-TARGET-CPU.md +++ b/src/guidelines/apps/M-TARGET-CPU.md @@ -12,6 +12,11 @@ This can be achieved, for example, by setting inside `.cargo/config.toml`: ```toml [target.x86_64-unknown-linux-gnu] rustflags = ["-C", "target-cpu=x86-64-v3"] + +[target.x86_64-pc-windows-msvc] +rustflags = ["-C", "target-cpu=x86-64-v3"] + +# Add other platforms here based on needs ... ``` Note this guideline applies only to applications, as target settings are ignored for libraries. diff --git a/src/guidelines/checklist/README.md b/src/guidelines/checklist/README.md index 7298826..11f64d4 100644 --- a/src/guidelines/checklist/README.md +++ b/src/guidelines/checklist/README.md @@ -43,6 +43,7 @@ - [ ] I/O and system calls are mockable ([M-MOCKABLE-SYSCALLS]) - [ ] Test utilities are feature gated ([M-TEST-UTIL]) - [ ] Integration tests live under `tests/` ([M-INTEGRATION-TESTS]) + - [ ] Integration test utilities live in a separate crate ([M-INTEGRATION-TEST-UTILS]) - [ ] Use the proper type family ([M-STRONG-TYPES]) - [ ] Newtypes guard their invariants ([M-STRONG-TYPES-GUARD]) - [ ] Builders validate in final `.build()` ([M-BUILD-RESULT]) @@ -86,6 +87,7 @@ - [ ] Shrink collections to fit after building ([M-SHRINK-TO-FIT]) - [ ] Use a fast hasher where possible ([M-FAST-HASHER]) - [ ] Collections are created with sufficient initial capacity ([M-INITIAL-CAPACITY]) + - [ ] Hot `async` functions reduce stack size ([M-ASYNC-STACK-SIZE]) - **Project** - [ ] Common settings come from the workspace Cargo.toml ([M-CARGO-WORKSPACE]) - [ ] The workspace lists and versions all crates ([M-CRATES-IN-WORKSPACE]) @@ -154,6 +156,7 @@ [M-EXT-TRAITS-FOREIGN-ITEMS]: ../libs/ux/#M-EXT-TRAITS-FOREIGN-ITEMS [M-TEST-UTIL]: ../libs/resilience/#M-TEST-UTIL [M-INTEGRATION-TESTS]: ../libs/resilience/#M-INTEGRATION-TESTS +[M-INTEGRATION-TEST-UTILS]: ../libs/resilience/#M-INTEGRATION-TEST-UTILS [M-AVOID-STATICS]: ../libs/resilience/#M-AVOID-STATICS [M-OOBE]: ../libs/building/#M-OOBE [M-SYS-CRATES]: ../libs/resilience/#M-SYS-CRATES @@ -185,6 +188,7 @@ [M-SHRINK-TO-FIT]: ../performance/#M-SHRINK-TO-FIT [M-FAST-HASHER]: ../performance/#M-FAST-HASHER [M-INITIAL-CAPACITY]: ../performance/#M-INITIAL-CAPACITY +[M-ASYNC-STACK-SIZE]: ../performance/#M-ASYNC-STACK-SIZE [M-CARGO-WORKSPACE]: ../project/#M-CARGO-WORKSPACE diff --git a/src/guidelines/ffi/M-FFI-NAMING.md b/src/guidelines/ffi/M-FFI-NAMING.md index 41aab65..0a366e3 100644 --- a/src/guidelines/ffi/M-FFI-NAMING.md +++ b/src/guidelines/ffi/M-FFI-NAMING.md @@ -10,4 +10,4 @@ Crates used for FFI should follow established naming practices: - `-sys` for crates defining items to call into existing (C-style) libraries - `-ffi` for crates defining (C-style) items when called from existing applications -There are slight variations of this scheme (e.g., `-sys2` when a previous `-sys` crate was abandoned and using `-` vs `_`), but overall one clearly defines 'export' libraries, the other one 'import' ones. +There are slight variations of this scheme (e.g., `-sys2` when a previous `-sys` crate was abandoned and using `-` vs `_`), but overall `-ffi` clearly defines 'export' libraries, and `-sys` 'import' ones. diff --git a/src/guidelines/libs/resilience/M-BUILD-RESULT.md b/src/guidelines/libs/resilience/M-BUILD-RESULT.md index 78e501a..c10e587 100644 --- a/src/guidelines/libs/resilience/M-BUILD-RESULT.md +++ b/src/guidelines/libs/resilience/M-BUILD-RESULT.md @@ -23,3 +23,5 @@ Foo::builder() .distance(42) .build()?; ``` + +That said, individual settings should prefer strong types carrying their own validation where applicable, compare M-STRONG-TYPES-GUARD. diff --git a/src/guidelines/libs/resilience/M-INTEGRATION-TEST-UTILS.md b/src/guidelines/libs/resilience/M-INTEGRATION-TEST-UTILS.md new file mode 100644 index 0000000..24b478d --- /dev/null +++ b/src/guidelines/libs/resilience/M-INTEGRATION-TEST-UTILS.md @@ -0,0 +1,13 @@ + + +## Integration test utilities live in a separate crate (M-INTEGRATION-TEST-UTILS) { #M-INTEGRATION-TEST-UTILS } + +To keep test scaffolding reusable across integration tests without polluting the production crate or duplicating helpers per test binary. +0.1 + +For complex projects, shared helpers used by integration tests (fixtures, builders, mock servers, assertion helpers, ...) should live in a dedicated crate rather than inside the production crate or copied between individual `tests/*.rs` files. + +- TODO: Define what counts as a "complex project" (e.g., number of integration tests, crates, or helpers that triggers this rule). +- TODO: Specify the recommended crate name / location convention (e.g., sibling `foo-test-utils` crate in the workspace). +- TODO: Clarify the relationship with [M-TEST-UTIL](#M-TEST-UTIL) (feature-gated helpers within a crate) — when to prefer which. +- TODO: Add a short example showing the crate layout and how integration tests depend on it (likely via `[dev-dependencies]`). diff --git a/src/guidelines/libs/resilience/M-INTEGRATION-TESTS.md b/src/guidelines/libs/resilience/M-INTEGRATION-TESTS.md index 82e9fc8..d345f07 100644 --- a/src/guidelines/libs/resilience/M-INTEGRATION-TESTS.md +++ b/src/guidelines/libs/resilience/M-INTEGRATION-TESTS.md @@ -7,4 +7,4 @@ Tests that only touch public API surface are _integration tests_ and belong under `tests/`, not `mod tests {}`. -In projects with coverage targets, it is not uncommon for `src/` files to contain more testing code than actual business logic. This can make browsing and understanding the code harder both in IDEs and PRs. Likewise, if a testing goal can be achieved through either an integration test or a unit test, the former is always preferred. Shared helpers between integration tests should live in a subdirectory module, e.g., `tests/common/mod.rs`. +In projects with coverage targets, it is not uncommon for `src/` files to contain more testing code than actual business logic. This can make browsing and understanding the code harder both in IDEs and PRs. Likewise, if a testing goal can be achieved through either an integration test or a unit test, the former is always preferred. diff --git a/src/guidelines/libs/resilience/M-PANIC-MESSAGE.md b/src/guidelines/libs/resilience/M-PANIC-MESSAGE.md index cb3efe4..7638cbd 100644 --- a/src/guidelines/libs/resilience/M-PANIC-MESSAGE.md +++ b/src/guidelines/libs/resilience/M-PANIC-MESSAGE.md @@ -14,3 +14,7 @@ assert!(buffer.len() >= HEADER_SIZE); // Good, message contains reason and actual values. assert!(buffer.len() >= HEADER_SIZE, "buffer too small for header: got {} bytes, need {HEADER_SIZE}", buffer.len()); ``` + +Messages related to API misuse should be useful to the end user. Messages indicating bugs should be helpful to you-as-the-author, or whoever maintains the project after you, to quickly identify the underlying cause. + +Panic messages in tests are not generally needed. diff --git a/src/guidelines/libs/resilience/M-STRONG-TYPES-GUARD.md b/src/guidelines/libs/resilience/M-STRONG-TYPES-GUARD.md index ab3705d..248ad72 100644 --- a/src/guidelines/libs/resilience/M-STRONG-TYPES-GUARD.md +++ b/src/guidelines/libs/resilience/M-STRONG-TYPES-GUARD.md @@ -31,6 +31,11 @@ impl Month { This means for any newtype that is non-total: - It must have at least one fallible constructor (e.g., `fn from_foo(...) -> Result`). -- Additional panicking constructors are allowed (e.g., `new`), but should preferably be `const`. +- Additional panicking constructors are allowed (e.g., `new`), and should preferably be `const`. - Conversions from weaker types into the newtype must be fallible (`TryFrom`/`FromStr`). - Infallible `From` implementations may not be offered. + +> ### Why `const`? +> +> Const constructors allows them to be used inside `const {}` blocks, which surfaces these violations as errors. This enables +> users to do `let month_due = const { Month::new(14) }` and avoids hitting these paths during runtime. diff --git a/src/guidelines/libs/resilience/README.md b/src/guidelines/libs/resilience/README.md index eea61dd..e4a5d56 100644 --- a/src/guidelines/libs/resilience/README.md +++ b/src/guidelines/libs/resilience/README.md @@ -5,6 +5,7 @@ {{#include M-MOCKABLE-SYSCALLS.md}} {{#include M-TEST-UTIL.md}} {{#include M-INTEGRATION-TESTS.md}} +{{#include M-INTEGRATION-TEST-UTILS.md}} {{#include M-STRONG-TYPES.md}} {{#include M-STRONG-TYPES-GUARD.md}} {{#include M-BUILD-RESULT.md}} diff --git a/src/guidelines/libs/ux/M-ASYNC-FN.md b/src/guidelines/libs/ux/M-ASYNC-FN.md index d9b4598..fd46f18 100644 --- a/src/guidelines/libs/ux/M-ASYNC-FN.md +++ b/src/guidelines/libs/ux/M-ASYNC-FN.md @@ -7,7 +7,7 @@ Functions should be declared `async fn foo()` over `fn foo() -> impl Future` when both are viable. -Functions marked `async` are more idiomatic and easier to read. An explicit `Future`-returning signature should only be used when required, for example inside traits. +Functions marked `async` are more idiomatic and easier to read. An explicit `Future`-returning signature should only be used when required, for example inside traits or for _hot 'n heavy_ async functions, compare [M-ASYNC-STACK-SIZE](../../performance/#M-ASYNC-STACK-SIZE). ```rust impl Foo { diff --git a/src/guidelines/macros/M-MACRO-MAIN-CRATE.md b/src/guidelines/macros/M-MACRO-MAIN-CRATE.md index aeaa3ed..aba2268 100644 --- a/src/guidelines/macros/M-MACRO-MAIN-CRATE.md +++ b/src/guidelines/macros/M-MACRO-MAIN-CRATE.md @@ -13,4 +13,6 @@ For crates including proc macros it is common to ship them split in 3 for techni - `foo_proc` - facade re-exporting macros from `foo_proc_impl` with `proc-macro = true`, - `foo_proc_impl` - the actual macro implementation and unit tests. -In some cases there can be additional crates involved. Authors might be tempted to make `foo`, `foo_proc`, and siblings all work, resulting in complex re-export hierarchies or the use of 3rd party helpers. In reality, the minimal UX gain is usually not worth the added complexity (or compile time overhead), given the ecosystem precedent of mostly not supporting these usage modes in the first place. +In some cases there can be additional crates involved. Authors might be tempted to make `foo`, `foo_proc`, and siblings all work, resulting in complex re-export hierarchies or the use of 3rd party helpers. In reality, the minimal UX gain is usually not worth the added complexity (or compile time overhead), given the ecosystem precedent of mostly not supporting these usage modes in the first place. + +This also implies you should not attempt to support use cases where your crate is imported under a different name. diff --git a/src/guidelines/macros/M-MACROS-DONT-LIE.md b/src/guidelines/macros/M-MACROS-DONT-LIE.md index 67742e7..1058fc3 100644 --- a/src/guidelines/macros/M-MACROS-DONT-LIE.md +++ b/src/guidelines/macros/M-MACROS-DONT-LIE.md @@ -11,7 +11,7 @@ Macros have the ability to arbitrarily rewrite token streams. They could convert Among others, macros must not -- convert the nature of data types (e.g., structs to enums, ...), +- visibly convert the nature of data types (e.g., structs to enums, ...), - alter function signatures, - convert the `async`-ness of items, - do anything else that materially detaches _what's written_ from _what's happening_. diff --git a/src/guidelines/performance/M-ASYNC-STACK-SIZE.md b/src/guidelines/performance/M-ASYNC-STACK-SIZE.md new file mode 100644 index 0000000..44393f6 --- /dev/null +++ b/src/guidelines/performance/M-ASYNC-STACK-SIZE.md @@ -0,0 +1,77 @@ + + +## Hot `async` functions reduce stack size (M-ASYNC-STACK-SIZE) { #M-ASYNC-STACK-SIZE } + +To reduce async stack size and reduce memcpy overhead. +0.1 + +Functions marked `async` in the hot path should track their future sizes, and take one or more of the following steps to reduce their impact: + +- reduction of parameter and rval type size, +- reduction of type size of items held across `.await` points, +- returning `impl Future` and extracting setup logic from `async {}` capture. + +> ### Future 'Stack' Sizes +> +> In Futures, what would naively be considered _their stack_, is actually part of a significantly more complicated machinery under their hood. +> +> Regular locals, that only live momentarily between two `.await` points, still remain part of the runtime thread's regular stack. However, any locals that live across `.await` points, or parameters passed during construction, become part of that Future's state machine type, and the layout of this type is currently not as optimized as it could be. +> +> This not only can cause stack-to-heap memcpy operations when creating or boxing Futures, it can also force large upfront stack sizes of the hypothetical most deeply nested cross-async call stack of the involved async function (which, on a side note, is why they can't simply recurse). +> +> ```rust +> async fn foo(_large: Large) { +> let within_future = [0_u8; 1024]; // Crosses .await below, embedded in `foo` type +> let on_stack = [0_u8; 1024]; // Does not cross .await points, lives on stack +> let sneaky = Droppable::with_size(1024); // Secretly crosses .await point! +> dbg!(&on_stack, &sneaky); +> bar(&within_future).await; +> dbg!(&within_future); +> // <- `sneaky` dropped here, despite otherwise not being used! +> } +> +> let future = foo(Large::new()); // `Large` becomes embedded in `foo` type, +> // blowing up its size, despite it not even +> // being used. +> +> // Here, despite `foo` not running yet, we might consume up to `Large` + +> // 2kb of this thread's stack memory. Once we spawn this is memcpy'ed +> // to runtime Task structure: +> rt.spawn(future); +>``` + +For many async functions this isn't an issue, as their associated `Future`-cost is negligible. However, functions used along the hot path, that are either called or instantiated frequently (e.g., 1000's of calls per second or concurrent tasks) might benefit from monitoring and optimizations. + +Hot futures should be tracked via `size_of_val`: + +```rust +async fn hot() { ... } + +#[test] +fn has_reasonable_size() { + let f = hot(); + assert!(size_of_val(&f) < ...); // Determine value / limit at first run. +} +``` +Then consider a combination of the following: + +```rust +// 1) Return an `impl Future` instead, this prevents large arguments +// from infecting the future size, among others. +fn hot(args: Args) -> impl Future> { + // 2) Process arguments outside async context if processing does + // not require async functionality. + let args = args.do_something(); + + if args.invalid() { + // 3) Use `Either` to return a single `impl Future` type, as + // otherwise you'd have to invent a new type. + async { Err(InvalidArgs) }.left_future() + } else { + // 4) Chain future invocations via future helpers, which again + // prevents heavy locals from being passed through the state + // machine. + read(args).then(|x| foo(x)).right_future() + } +} +``` diff --git a/src/guidelines/performance/M-FAST-HASHER.md b/src/guidelines/performance/M-FAST-HASHER.md index c58a181..292d6a3 100644 --- a/src/guidelines/performance/M-FAST-HASHER.md +++ b/src/guidelines/performance/M-FAST-HASHER.md @@ -5,7 +5,7 @@ to improve performance. 0.1 -When hashing trusted, internal keys, prefer a fast non-cryptographic hasher (e.g., `FxHash`) over the standard library default. +When hashing trusted, internal keys, prefer a fast non-cryptographic hasher (e.g., `foldhash`, `FxHash`) over the standard library default. Rust's default hasher is reasonably DoS safe on untrusted user input, but this comes at a performance penalty. If you can trust that keys are not maliciously crafted to overflow individual buckets, a custom fast hasher can yield significant performance gains. @@ -13,6 +13,5 @@ Rust's default hasher is reasonably DoS safe on untrusted user input, but this c // Bad, uses default hasher for keys we control. let lookup = HashMap::::with_capacity(1024); -// Good, uses faster fxhash for internal keys. -let lookup = HashMap::::with_capacity(1024); -``` +// Good, uses faster foldhash for internal keys. +let lookup = foldhash::HashMap::with_capacity(1024); diff --git a/src/guidelines/performance/M-SHRINK-TO-FIT.md b/src/guidelines/performance/M-SHRINK-TO-FIT.md index d8e8e4a..4e3be32 100644 --- a/src/guidelines/performance/M-SHRINK-TO-FIT.md +++ b/src/guidelines/performance/M-SHRINK-TO-FIT.md @@ -7,7 +7,7 @@ Where large, long-lived, growable collections such as `Vec` or `String` were built without an exact size reservation (compare [M-INITIAL-CAPACITY](#M-INITIAL-CAPACITY)), the resulting collection should be shrunk via `shrink_to_fit` before storing it. -Rust's collections grow by powers of two when iteratively adding elements. In the worst case a collection might therefore use ~2x of its needed memory. +Many Rust collections grow by powers of two when iteratively adding elements. In the worst case a collection might therefore use ~2x of its needed memory. ```rust // Bad, long lived object might end up using 2x needed memory. diff --git a/src/guidelines/performance/README.md b/src/guidelines/performance/README.md index 201403d..ab0efc0 100644 --- a/src/guidelines/performance/README.md +++ b/src/guidelines/performance/README.md @@ -12,3 +12,4 @@ {{#include M-SHRINK-TO-FIT.md}} {{#include M-FAST-HASHER.md}} {{#include M-INITIAL-CAPACITY.md}} +{{#include M-ASYNC-STACK-SIZE.md}}