This page tracks notable changes to the Pragmatic Rust Guidelines.
This update substantially expanded the guidelines, adding 41 new entries spanning macros, performance, project layout, FFI, AI-assisted development, and more:
| Guideline | Title |
|---|---|
| M-ASYNC-FN | Functions are async over returning a Future |
| M-ASYNC-STACK-SIZE | Hot async functions reduce stack size |
| M-AVOID-INDIRECTION | Nested type hierarchies should avoid needless indirection |
| M-BALANCED-MODULES | Modules are balanced in size and scope |
| M-BOX-DST | Use boxed slices and strings for immutable owned sequences |
| M-BUILD-RESULT | Builders validate in final .build() |
| M-CARGO-WORKSPACE | Common settings come from the workspace Cargo.toml |
| M-COLLECTION-TRAITS | Collections implement the appropriate iter traits |
| M-CRATES-FLAT-FOLDER | All crates are siblings in one folder |
| M-CRATES-IN-WORKSPACE | The workspace lists and versions all crates |
| M-EXAMPLE-OVER-PROC | Prefer 'macros by example' over proc macros |
| M-FAST-HASHER | Use a fast hasher where possible |
| M-FFI-NAMING | FFI crates follow established naming conventions |
| M-FFI-TRANSLATES | Business logic belongs in core crates, FFI only translates |
| M-FOREIGN-REEXPORTS | Items come from their original crate |
| M-FROM-ERROR | Canonical error conversion uses From, not map_err |
| M-INITIAL-CAPACITY | Collections are created with sufficient initial capacity |
| M-INTEGRATION-TESTS | Integration tests live under tests/ |
| M-LATEST-EDITION | New crates target latest edition |
| M-LOG-NOT-PRINT | Production code uses telemetry, not println |
| M-LOG-OVERHEAD | Library telemetry does not tank performance |
| M-MACRO-HELPERS | Third party items come from hidden _private module |
| M-MACRO-LAST-RESORT | Macros are a last resort |
| M-MACRO-MAIN-CRATE | Macros assume main crate |
| M-MACROS-DONT-LIE | Macros don't lie about signatures |
| M-MEM-REUSE | Reuse allocations where possible |
| M-MSRV | MSRV is conservatively updated |
| M-NO-META-DESIGN-DOCUMENTATION | Avoid meta design documentation |
| M-NO-PRELUDE | Don't define preludes |
| M-PANIC-CONTINUATION | Panic continuation is last resort |
| M-PANIC-MESSAGE | Custom panics have a helpful message |
| M-PARAMETER-CONSISTENCY | Parameter ordering is consistent |
| M-PROC-IMPL | Proc macros should have separate impl crate incl. tests |
| M-PROC-IMPLIED-ITEMS | Proc macros don't produce implied or hidden items |
| M-RUST-SHAPED | Rust code solves Rust problems |
| M-SHORT-NAMES | Names of items are short |
| M-SHRINK-TO-FIT | Shrink collections to fit after building |
| M-SINGLE-ITEM-PATH | Items are only visible through one path |
| M-STRONG-TYPES-GUARD | Newtypes guard their invariants |
| M-TARGET-CPU | Applications target highest viable target-cpu |
| M-TAUTOLOGICAL-TESTS | Tests do not assert ground truth |
We also removed the guideline-specific versioning.
Initial release of the Pragmatic Rust Guidelines.