mre/idiomatic-rust

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

• Comprehensive Rust - A four day Rust course developed by the Android team, which covers all aspects of Rust, from basic syntax to generics and error handling. It also includes Android-specific content and touches on Rust ergonomics.
• 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.
• rust-lang/rustlings - 🦀 Small exercises to get you used to reading and writing 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 data structures 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.
• Programming Rust: Fast, Safe Systems Development - A comprehensive Rust Programming Guide that covers most of Rust's features in detail.
• Rust Atomics and Locks by Mara Bos - Helps Rust programmers of all levels gain a clear understanding of low-level concurrency.

📰 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 with map_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) and String (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 and Result (especially and_then() and unwrap_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> and AsMut<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 and Cow (Clone-on-write) work together to avoid allocations for string types.
• Effectively Using Iterators In Rust by @hjr - Explanation of the Iter and IntoIter 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

2023

• Tricks of the Trait: Enabling Ergonomic Extractors [Video] by Rob Ede - Rust Nation UK, Feb. 2023

2022

• Nine Rules for Elegant Rust Library APIs [Video] by Carl Kadie - Seattle Rust Meetup, Sep. 2022
• Ergonomic APIs for hard problems [Video] [Slides] by Raph Levien - RustLab Conference, October 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

• Preferred way of passing Path-like types around?

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.