.github | ||
.lycheeignore | ||
CONTRIBUTING.md | ||
idiomatic-rust.png | ||
idiomatic-rust.svg | ||
README.md |
This repository collects resources for writing clean, idiomatic Rust code. Please bring your own. 😊
Idiomatic coding means following the conventions of a given language. It is the most concise, convenient, and common way of accomplishing a task in that language, rather than forcing it to work in a way the author is familiar with from a different language. - Adapted from Tim Mansfield
⚙ Projects
- Rust Anthology - The best short-form writing about Rust, collected.
- blessed.rs - An unofficial guide to the Rust ecosystem. Suggestions for popular, well-maintained crates.
- cheats.rs - Idiomatic Rust tips - A list of quick tips to make your code more idiomatic.
- clippy - A bunch of lints to catch common mistakes and improve your Rust code.
- Patterns - A catalogue of design patterns in Rust.
- Elements of Rust - A collection of software engineering techniques for effectively expressing intent with Rust.
- Possible Rust - A blog for intermediate Rust programmers exploring real-world code and design patterns.
- Rust API Guidelines - An extensive list of recommendations for idiomatic Rust APIs.
- Rust by Example - A community driven collection of example code which follow Rust best practices.
🏋 Workshops
- Build your own JIRA with Rust - A test-driven workshop to learn Rust building your own JIRA clone!
- Ferrous Systems Teaching Material - Free workshop material produced by Ferrous Systems for trainings. The time for the full course is around three to four days.
- PingCAP talent plan - A series of training courses about writing distributed systems in Rust. The courses primarily consist of projects where coding problems are presented, along with a partial implementation or API description, and a test suite.
- Procedural Macros Workshop - This repo contains a selection of projects designed to learn to write Rust procedural macros — Rust code that generates Rust code.
📖 Books
- Command Line Applications in Rust - A tutorial on how to write CLI apps in Rust, learning many aspects of the ecosystem along the way.
- Command-Line Rust by Ken Youens-Clark - Learn the language by writing Rust versions of common Unix coreutils like head, tail, cal, cut, comm, etc.
- Discover the world of microcontrollers through Rust! - This book is an introductory course on microcontroller-based embedded systems that uses Rust as the teaching language rather than the usual C/C++.
- High Assurance Rust by Tiemoko Ballo - Developing Secure and Robust Software. Tackles implementing embedded-friendly datastructures in an idiomatic way.
- Rust Cookbook - Examples that demonstrate good practices to accomplish common programming tasks in Rust.
- Rust for Rustaceans by Jon Gjengset - Covers how to design reliable, idiomatic, and ergonomic Rust programs based on best principles.
📰 Articles
2021
- Naming Your Lifetimes by Possible Rust - Explains how using longer, declarative lifetime names can help to disambiguate which borrow is which, and where it’s coming from.
- Aiming for idiomatic Rust by Shane Osbourne - Discusses different ways to solve a popular coding puzzle, "balanced brackets", in Rust.
- Wrapping errors in Rust by Edgar Luque - Wrapping
reqwest::Error
and a custom error type as an enum to make library usage easier. Also mentions thiserror to automate that process. - Hexagonal architecture in Rust by Alexis Lozano - Describes how to build a Rust service using domain driven design and a test-first approach.
2020
- Context-preserving error handling by Simonas Kazlauskas - Explains how to use crates like
thiserror
in combination withmap_err
to add context to errors to prevent information loss. - Refactoring Rust Transpiled from C by Per Larsen - Describes how to lift a C-project that was automatically converted to unsafe Rust with C2Rust to safer, more idiomatic Rust with some human intervention.
- Learning Rust through open source and live code reviews by Luciano Mammino and Stefano Abalsamo - Covers patterns like FromStr and exposing a CLI and a library in one crate.
- Guide on how to write documentation for a Rust crate - Writing good documentation with rustdoc including many examples.
- Are out parameters idiomatic in Rust? - Discusses the pros and cons of functions returning a value vs. modifying a parameter in-place.
2019
- Await a minute by David Tolnay - Example code for moving from raw futures to async/await syntax to improve error handling, native control flow, and borrowing.
- Taking string arguments in Rust by @Xion - Discussing how to avoid subtle issues with string handling and when to use
str
(the string slice) andString
(the owned/allocated string). - Rust Patterns: Enums Instead Of Booleans by Blake Smith - Discusses how using enums instead of booleans can be useful to express intent more clearly without sacrificing safety thanks to Rust's strong semantics (like exhaustive pattern matching).
2018
- Programming an ARM microcontroller in Rust at four different levels of abstraction by Pramode C.E - Demonstrates how Rust helps to move from brittle, low-level embedded code to high-level abstractions with zero cost.
2017
- Iteration patterns for Result & Option by @Xion - Explores how to filter and partition iterators of Result and Option types idiomatically.
- Lessons learned redesigning and refactoring a Rust Library by @mgattozzi -
RefCell
, the builder pattern and more. - Math with distances in Rust: safety and correctness across units by @code-ape - How to create a system to cleanly and safely do arithmetic with lengths.
- The balance between cost, useability and soundness in C bindings, and Rust-SDL2's release by @Cobrand - Writing safe, sound, idiomatic libraries despite the limitations of the borrow checker.
2016
- Russian Dolls and clean Rust code by @mgattozzi - How to use the full power of
Option
andResult
(especiallyand_then()
andunwrap_or()
). - Elegant Library APIs in Rust by @killercup - Many helpful tips and tricks for writing libraries in Rust.
- Teaching libraries through good documentation by @killercup - How to use the full power of Rust's documentation support (e.g. doc tests)
- Pretty State Machine Patterns in Rust by @hoverbear - How to represent a State Machine in an expressive and understandable way in Rust.
- Ripgrep Code Review by @mbrt - An analysis of the popular
ripgrep
tool's source code. - Rustic Bits by @llogiq - Small things that make for rustic code.
- Convenient and idiomatic conversions in Rust by meqif - Explains
From<T>
,Into<T>
,TryFrom<T>
,TryInto<T>
,AsRef<T>
andAsMut<T>
with pratical examples. - Idiomatic tree and graph like structures in Rust by saschagrunert - Introduction to safe, dynamic, arena based tree structures without using lifetimes.
2015
- Rust traits for developer friendly libraries by @benashford - Thoughts about implementing good Rust libraries.
- Error Handling in Rust by @BurntSushi - Understanding and handling errors in Rust in an idiomatic way.
- Creating a Rust function that accepts String or &str by @hjr - How to make calling your code both ergonomic and fast (zero-allocation).
- Creating a Rust function that returns a &str or String by @hjr - How
Into
andCow
(Clone-on-write) work together to avoid allocations for string types. - Effectively Using Iterators In Rust by @hjr - Explanation of the
Iter
andIntoIter
traits and how loops actually work in Rust. - Strategies for solving 'cannot move out of' borrowing errors in Rust by @hjr - Practical tips to help understand the borrow-checker and move semantics.
- Rayon: data parallelism in Rust by @nikomatsakis - Writing elegant parallel code in Rust.
🎤 Talks
2022
Nine Rules for Elegant Rust Library APIs [Video] by Carl Kadie - Seattle Rust Meetup, Sep. 2022
2020
Macros for a More Productive Rust [Video] by @jam1garner - RustConf 2020
2019
Making Rust Delightful [Video] by @nrc - RustCon Asia 2019
2018
Idiomatic Rust - Writing Concise and Elegant Rust Code [Video] [Slides] by @mre - FOSDEM 2018
2017
Idiomatic Rust Libraries [Video] [Slides] by @killercup - Rustfest Kiev
What's so hard about writing a Slack Client in Rust? [Video] [Slides] by @mre - Rust Cologne Meetup
💬 Forum
2020
2017
- Which is more idiomatic? Functional, imperative or a mix?
- An idiomatic way to sum up values in a multidimensional Array
📜 History
Coming from Python, I loved the guidelines on how idiomatic Python looks like. I was inspired by the likes of Peter Norvig, who wrote amazing articles on spellcheckers and sudoku solvers; and, of course, the Zen of Python. For Rust, there is no such thing as the Zen of Python, however, so I started collecting my own resources. The goal of this project is to create a peer-reviewed collection of articles/talks/repos, which teach idiomatic Rust style. It's a community project and you can contribute.
🔏 License
To the extent possible under law, Matthias Endler has waived all copyright and related or neighboring rights to this work. Logo adapted from FreePik.com.