From 5cc77138b2190d3d462a0b804e2142cef8095714 Mon Sep 17 00:00:00 2001 From: Rodin <4+rodin@noreply.gitea.weiker.me> Date: Fri, 8 May 2026 01:10:03 +0000 Subject: [PATCH] docs: align README with elixir/go pattern repos MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Consistent structure: prescriptive header, structure, agent instructions (solving/reviewing/evaluating), taxonomy definition. Removed discovery data table and line counts — the patterns speak for themselves. --- README.md | 132 ++++++++++++++++++++++++------------------------------ 1 file changed, 58 insertions(+), 74 deletions(-) diff --git a/README.md b/README.md index 5a11350..1284e56 100644 --- a/README.md +++ b/README.md @@ -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 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