From 791c7b0fed3321960125556c713c94c32cac46b6 Mon Sep 17 00:00:00 2001 From: Rodin Date: Thu, 30 Apr 2026 15:13:38 -0700 Subject: [PATCH] docs: comprehensive README with stats and usage guide 100 patterns across 10 files, 6,441 lines total. Includes discovery data table, pattern file index, and usage guide. --- README.md | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 81 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index fcdeff9..258ddfc 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,82 @@ -# rust-patterns +# Rust Patterns -Idiomatic Rust patterns extracted from rust-lang/rust source \ No newline at end of file +Prescriptive patterns for writing idiomatic Rust, extracted from the +standard library source at [rust-lang/rust](https://github.com/rust-lang/rust). + +## Source + +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). + +## 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 | + +**Total: 100 patterns across 10 files, 6,441 lines.** + +## Discovery Data (from library/) + +| 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 | + +## Each Pattern Includes + +- **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 + +## 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).