rodin/rust-patterns
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: align README with elixir/go pattern repos

Browse Source 
Consistent structure: prescriptive header, structure, agent
instructions (solving/reviewing/evaluating), taxonomy definition.
Removed discovery data table and line counts — the patterns
speak for themselves.
This commit is contained in:
Rodin
2026-05-08 01:10:03 +00:00
parent d78abb3183
commit 5cc77138b2
1 changed files with 58 additions and 74 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+58 -74
View File
@@ -1,95 +1,79 @@
# Rust Patterns
Prescriptive patterns for writing idiomatic Rust, extracted from the
standard library source at [rust-lang/rust](https://github.com/rust-lang/rust).
**Prescriptive.** Follow these when writing Rust code.
## Source
A pattern is a reusable solution to a recurring problem. Each one has:
- **When to use** — the problem it solves
- **When NOT to use** — where it causes harm
- **Why** — the reasoning, not just the rule
- **Source citations** — permalink to the exact source location
All patterns are extracted from the `library/` directory (the standard
library implementation) at commit
[`f53b654`](https://github.com/rust-lang/rust/tree/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6)
(325,000 commits, 8,021 contributors).
These are derived from what the [Rust standard library](https://github.com/rust-lang/rust) *actually does*, not opinions or blog posts.
## Structure
- `patterns/` — what to do (error handling, ownership, traits, concurrency, unsafe, macros, etc.)
- `smells/` — what NOT to do (anti-patterns, common mistakes)
## Pattern Files
| File | Patterns | Lines | Key Topics |
|------|----------|-------|------------|
| [error-handling.md](patterns/error-handling.md) | 10 | 702 | Result, ?, Error trait, From, panic! |
| [traits.md](patterns/traits.md) | 10 | 699 | Small traits, derive, From/Into, Iterator, Deref |
| [ownership.md](patterns/ownership.md) | 10 | 677 | Borrowing, Clone/Copy, Cow, Arc, Drop, lifetimes |
| [documentation.md](patterns/documentation.md) | 10 | 723 | Doc comments, # Safety, # Examples, doc tests |
| [concurrency.md](patterns/concurrency.md) | 10 | 723 | Send/Sync, Mutex, atomics, channels, scoped threads |
| [testing.md](patterns/testing.md) | 10 | 664 | cfg(test), assert_eq!, should_panic, property tests |
| [unsafe-patterns.md](patterns/unsafe-patterns.md) | 10 | 624 | // SAFETY:, unsafe fn, MaybeUninit, FFI |
| [api-design.md](patterns/api-design.md) | 10 | 596 | Naming, #[non_exhaustive], newtype, typestate |
| [module-organization.md](patterns/module-organization.md) | 10 | 514 | File structure, pub use, prelude, workspaces |
| [macros.md](patterns/macros.md) | 10 | 519 | macro_rules!, derive, attribute macros, hygiene |
| File | Patterns | Key Topics |
|------|----------|------------|
| [error-handling.md](patterns/error-handling.md) | 10 | Result, ?, Error trait, From, panic! |
| [traits.md](patterns/traits.md) | 10 | Small traits, derive, From/Into, Iterator, Deref |
| [ownership.md](patterns/ownership.md) | 10 | Borrowing, Clone/Copy, Cow, Arc, Drop, lifetimes |
| [documentation.md](patterns/documentation.md) | 10 | Doc comments, # Safety, # Examples, doc tests |
| [concurrency.md](patterns/concurrency.md) | 10 | Send/Sync, Mutex, atomics, channels, scoped threads |
| [testing.md](patterns/testing.md) | 10 | cfg(test), assert_eq!, should_panic, property tests |
| [unsafe-patterns.md](patterns/unsafe-patterns.md) | 10 | // SAFETY:, unsafe fn, MaybeUninit, FFI |
| [api-design.md](patterns/api-design.md) | 10 | Naming, #[non_exhaustive], newtype, typestate |
| [module-organization.md](patterns/module-organization.md) | 10 | File structure, pub use, prelude, workspaces |
| [macros.md](patterns/macros.md) | 10 | macro_rules!, derive, attribute macros, hygiene |
**Total: 100 patterns across 10 files + 20 smells across 2 files = 7,439 lines.**
## How to use
## Discovery Data (from library/)
Give your agent these instructions depending on the task:
| Category | Metric | Count |
|----------|--------|-------|
| Error Handling | `?` operator usages | 4,702 |
| Error Handling | `Result<>` types | 4,059 |
| Error Handling | `From<>` impls | 508 |
| Traits | Public traits | 241 |
| Traits | Trait implementations | 4,387 |
| Traits | Iterator impls | 895 |
| Ownership | `&mut` references | 7,909 |
| Ownership | Rc/Arc usages | 798 |
| Ownership | Cow<> usages | 197 |
| Documentation | Doc comments (///) | 133,741 |
| Documentation | # Examples sections | 3,912 |
| Documentation | # Safety sections | 2,864 |
| Concurrency | Atomic types | 783 |
| Concurrency | Send/Sync markers | 274 |
| Testing | #[test] functions | 4,136 |
| Testing | Assert macros | 16,728 |
| Unsafe | Unsafe blocks | 31,244 |
| Unsafe | // SAFETY: comments | 2,463 |
| API Design | pub fn | 18,430 |
| API Design | pub(crate) | 919 |
| Macros | macro_rules! | 607 |
| Macros | #[derive(...)] | 1,116 |
### Solving a problem
## Smell Files
> You have access to a patterns repo containing proven solutions to recurring Rust problems. When I describe a problem:
>
> 1. Identify which pattern files are relevant (read them)
> 2. Check if my problem matches a "When to use" case
> 3. Check if it matches a "When NOT to use" case
> 4. If a pattern fits: suggest the approach, cite the pattern, explain why it applies here
> 5. If no pattern fits: say so, and suggest an approach grounded in the principles you see across the patterns
> 6. If my problem matches a smell: warn me before I make the mistake
>
> Never suggest something that contradicts a documented pattern without explicitly calling out the deviation and justifying it.
| File | Entries | Lines | Key Topics |
|------|---------|-------|------------|
| [smells/anti-patterns.md](smells/anti-patterns.md) | 10 | 490 | unwrap in libs, String errors, unsafe without SAFETY, clone escape |
| [smells/common-mistakes.md](smells/common-mistakes.md) | 10 | 508 | Arc<Mutex> everywhere, collect then iterate, index loops, OOP thinking |
### Reviewing code
## Each Pattern Includes
> You have access to a patterns repo that defines how Rust code should be written. For each file in the diff:
>
> 1. Read the relevant pattern files
> 2. Verify the code follows the documented patterns
> 3. If it deviates: flag it with a reference to the specific pattern, section, and why it matters
> 4. If it matches a smell: flag it as a known anti-pattern
> 5. A deviation without justification is a finding
>
> Don't invent rules. Only flag what the patterns document.
- **Source hyperlink** — permalink to the exact source location
- **Before/After code** — concrete transformation showing improvement
- **When to Use** — trigger conditions (when this pattern applies)
- **When NOT to Use** — over-application warning with code example
- **Decision tree** — at the end of each file for quick reference
### Evaluating a pattern
## How to Use This Repo
1. **Learning Rust**: Read patterns in order of importance:
error-handling → ownership → traits → concurrency
2. **Code review**: Reference specific patterns when reviewing Rust PRs
3. **Teaching**: Use before/after pairs as exercises
4. **Writing new code**: Check the decision tree before choosing an approach
## Related Repos
- [rodin/go-patterns](https://gitea.weiker.me/rodin/go-patterns) — Go patterns from stdlib
- [rodin/elixir-patterns](https://gitea.weiker.me/rodin/elixir-patterns) — Elixir patterns from stdlib
- [rodin/codebase-analysis](https://gitea.weiker.me/rodin/codebase-analysis) — The skill that produces these repos
## License
This repository contains analysis and patterns derived from
rust-lang/rust (MIT/Apache-2.0 dual licensed).
> Read the pattern file. Compare against how the following projects handle the same problem: [list projects]. Does the pattern hold? Are there cases where it breaks down? Should it be updated, split, or retired? File your findings as an issue.
## Patterns vs Conventions
**Pattern** = prescriptive. "When you face X, do Y." Language-scoped. Follow these.
**Convention** = descriptive. "Project Z does it this way." Context-specific. Study for ideas — applying another project's conventions to yours without understanding their constraints causes harm.
## Source
All patterns extracted from `library/` at commit [`f53b654`](https://github.com/rust-lang/rust/tree/f53b654a8882fd5fc036c4ca7a4ff41ce32497a6) (325,000 commits, 8,021 contributors).
## Related Repos
- [rodin/go-patterns](https://gitea.weiker.me/rodin/go-patterns) — Go patterns from stdlib
- [rodin/elixir-patterns](https://gitea.weiker.me/rodin/elixir-patterns) — Elixir patterns from stdlib