Idiomatic-Rust on

Lesson 25: When to Reach for unsafe — And when not to

Wed, 22 May 2024 17:08:00 +0000

This is the lesson I almost didn’t write. Not because unsafe is hard to explain, but because most Rust developers will never need it — and I don’t want to encourage reaching for it prematurely. I’ve seen codebases riddled with unsafe blocks because the developer didn’t know the safe alternative existed. That’s the worst outcome.

But unsafe exists for a reason. Understanding when it’s appropriate — and more importantly, when it isn’t — is part of being a competent Rust developer.

Lesson 24: Writing Great Rust Documentation — rustdoc that actually helps

Mon, 20 May 2024 14:30:00 +0000

The Rust ecosystem has some of the best documentation I’ve seen in any language. And it’s not an accident — the tooling actively encourages good documentation. Doc comments are first-class citizens. Examples in docs are compiled and tested. The standard library sets an impossibly high bar that crate authors actually try to meet.

If you’re publishing a crate and the docs are an afterthought, you’re doing it wrong. Documentation is the API.

Lesson 23: Clippy Is Your Mentor — Listen to it

Sat, 18 May 2024 10:55:00 +0000

I’ll say something controversial: Clippy taught me more about idiomatic Rust than any book. Not because it explains concepts — it doesn’t. But because it catches you every time you write non-idiomatic code and shows you the better way. It’s like having a senior Rust developer looking over your shoulder, constantly saying “there’s a cleaner way to do that.”

Run cargo clippy on every project. Every commit. No exceptions.

What Clippy Is

Clippy is Rust’s official linter — over 700 lint rules that catch everything from style issues to actual bugs. It ships with rustup, so you already have it.

Lesson 22: Feature Flags and Conditional Compilation — cfg and features

Thu, 16 May 2024 12:45:00 +0000

I once worked on a crate that pulled in 200+ transitive dependencies because it unconditionally depended on tokio, serde, reqwest, and tracing. Most users only needed one of those. The compile time was brutal, and the binary was enormous.

Feature flags solve this. They let users opt into functionality they need and skip everything else. It’s the “pay for what you use” principle applied to compilation.

cfg — Conditional Compilation

The #[cfg(...)] attribute conditionally includes code based on compile-time configuration:

Lesson 21: The Turbofish ::<> — Explicit type parameters

Tue, 14 May 2024 08:22:00 +0000

The first time I saw ::<> in Rust code, I thought someone was having a stroke at the keyboard. collect::<Vec<_>>()? What is that colon-colon-angle-bracket monstrosity?

It’s called the turbofish. Named by the community because ::<> looks like a fish (::<> — see the eyes and the mouth?). It’s goofy. It’s lovable. And once you understand it, you’ll use it constantly.

What the Turbofish Does

The turbofish provides explicit type parameters to generic functions or methods when the compiler can’t infer them.

Lesson 20: API Design Guidelines — The Rust way

Sun, 12 May 2024 16:40:00 +0000

I’ve written APIs in a dozen languages, and Rust is the only one where the community has near-universal agreement on how APIs should look. There’s an unofficial (but incredibly thorough) Rust API Guidelines document, and most popular crates follow it closely. When you learn these conventions, every new crate feels familiar.

Here’s what I’ve distilled from reading hundreds of crate APIs and writing a few of my own.

Naming Conventions

Rust has strong naming conventions, and deviating from them makes your crate feel alien.

Lesson 19: PhantomData — Tagging types without runtime cost

Fri, 10 May 2024 09:15:00 +0000

When I first saw PhantomData in a codebase, I thought it was some kind of hack. A zero-sized field that exists only to satisfy the compiler? It felt like a workaround for a language limitation. But the more I used it, the more I realized it’s actually a precision tool — it lets you encode information in the type system without any runtime cost.

We already used it in the typestate lesson. Now let’s understand it properly.

Lesson 18: Drop and RAII — Deterministic cleanup

Wed, 08 May 2024 11:30:00 +0000

In Go, you write defer f.Close() and hope you didn’t forget one. In Python, you use with blocks and hope the context manager is implemented correctly. In Java, you use try-with-resources and hope AutoCloseable.close() doesn’t throw. In C, you write free() and pray.

In Rust, cleanup happens automatically when a value goes out of scope. Always. No exceptions. No forgetting. That’s RAII — Resource Acquisition Is Initialization — and the Drop trait is how Rust implements it.

Lesson 17: Zero-Cost Abstractions — What it actually means

Mon, 06 May 2024 14:52:00 +0000

“Zero-cost abstractions” is Rust’s most-repeated promise and its most-misunderstood concept. People hear “zero cost” and think “free.” It doesn’t mean free. It means: you don’t pay for what you don’t use, and what you do use, you couldn’t hand-code any better.

That’s a Bjarne Stroustrup quote, originally about C++. But Rust actually delivers on it in ways C++ often doesn’t.

What Zero-Cost Actually Means

Consider iterators. In Python, iterator chains create intermediate objects. In Java, streams can have overhead from boxing and virtual dispatch. In Rust:

Lesson 16: Enums Over Booleans — Make illegal states unrepresentable

Sun, 05 May 2024 08:17:00 +0000

I once spent an entire afternoon debugging a function with this signature: process(data, true, false, true). Three booleans. What did they mean? I had to read the function definition every single time I encountered a call site. Is true for “verbose”? For “dry-run”? For “force”?

Booleans are the most overused type in programming. They encode exactly one bit of information — yes or no — and they tell you nothing about what question they’re answering. Enums fix this.

Lesson 15: Exhaustive Matching — Let the compiler help

Fri, 03 May 2024 22:08:00 +0000

A teammate once added a new payment method to our system — CryptoCurrency — and forgot to update the fee calculation logic. In production. For three weeks. Nobody noticed because the switch statement in Java had a default case that silently applied a 0% fee. Free crypto transfers for everyone.

In Rust, the compiler would have caught this the moment the new variant was added. That’s exhaustive matching — and it’s one of Rust’s most underappreciated features.

Lesson 14: derive Is Your Best Friend — The macros you should always use

Thu, 02 May 2024 10:30:00 +0000

I review a lot of Rust code, and one of my biggest pet peeves is types without #[derive(Debug)]. You hit an error, you try to print the value, and you get that lovely message: “MyStruct doesn’t implement Debug.” Then you have to go add it, recompile, and try again.

Just derive it from the start. Derive liberally. Your future self will thank you.

The Derives You Should Almost Always Use

Here’s my standard starting point for any struct or enum:

Lesson 13: Display and Debug — Formatting done right

Tue, 30 Apr 2024 18:45:00 +0000

Pop quiz: what’s the difference between {} and {:?} in a println!? If your answer is “one looks prettier,” you’re not wrong — but you’re missing the bigger picture.

Display and Debug serve fundamentally different audiences. Display is for humans — end users, log readers, UI consumers. Debug is for developers — it’s what you see in error messages, test failures, and debug sessions. Conflating the two leads to types that are either too verbose for users or too opaque for debugging.

Lesson 12: Designing Error Types — thiserror vs anyhow

Mon, 29 Apr 2024 12:18:00 +0000

I’ve seen two extremes in Rust error handling. On one end: Box<dyn std::error::Error> everywhere, a stringly-typed mess where you can’t distinguish a network timeout from a parse failure. On the other end: 47 custom error types with hand-written Display and From implementations, an over-engineered cathedral of boilerplate.

The right answer is somewhere in the middle. And the two crates that get you there are thiserror and anyhow.

The Wrong Ways

Wrong Way #1: String Errors

fn parse_config(input: &str) -> Result<u16, String> {
 let port: u16 = input.parse().map_err(|e| format!("bad port: {}", e))?;
 if port < 1024 {
 return Err("port must be >= 1024".to_string());
 }
 Ok(port)
}

The caller gets a String. What can they do with it? Print it. That’s about it. They can’t match on error variants, can’t programmatically decide how to handle different failures, can’t distinguish between “bad port” and “port too low.” It’s a dead end.

Lesson 11: Cow — Clone on write for flexible APIs

Sat, 27 Apr 2024 15:33:00 +0000

There’s a function signature dilemma that every Rust developer hits: should this function return &str or String? If you return &str, you avoid allocation — but sometimes you need to create a new string. If you return String, you allocate every time — even when you don’t need to.

Cow says: “Why not both?”

The name stands for “Clone on Write,” and it’s one of those types that seems weird until you use it — and then you wonder how you lived without it.

Lesson 10: Deref Coercion — Why &String works as &str

Thu, 25 Apr 2024 21:10:00 +0000

Here’s something that confused me for weeks when I started Rust: I’d write a function that takes &str, and I could pass it a &String. I’d write a function that takes &[i32], and I could pass it a &Vec<i32>. I’d use * to dereference a Box<T> and get a T.

How? Why? The answer is Deref coercion — one of Rust’s most elegant features, and one of the most poorly explained.

Lesson 9: From and Into — Seamless type conversions

Wed, 24 Apr 2024 07:55:00 +0000

The first time I saw .into() in Rust code, I was baffled. “Into what?” There was no type annotation, no explicit conversion function, just .into() hanging off a value like it knew exactly what to become. And somehow the compiler figured it out.

That’s the From/Into trait pair. It’s one of the most-used patterns in idiomatic Rust, and once you understand it, your APIs will feel dramatically smoother.

The Basics: `From` and `Into` Are Mirror Images

// If you implement From<A> for B...
impl From<i32> for MyType {
 fn from(value: i32) -> Self {
 MyType(value)
 }
}

// ...you get Into<B> for A for free
let x: MyType = 42.into();

Always implement From, never Into directly. The standard library provides a blanket implementation: if From<A> exists for B, then Into<B> is automatically available for A. Implementing Into directly doesn’t give you the reverse.

Lesson 8: The Builder Pattern in Rust — Ergonomic construction

Mon, 22 Apr 2024 19:42:00 +0000

Every Rust dev eventually runs into the “struct with 12 fields” problem. You’ve got a configuration type. Some fields are required, some are optional, some have sensible defaults. In Java, you’d use a Builder. In Python, you’d use keyword arguments. In Go, you’d use functional options.

In Rust? You have options. And one of them is clearly better than the rest.

The Problem: Constructor Explosion

struct ServerConfig {
 host: String,
 port: u16,
 max_connections: usize,
 timeout_secs: u64,
 tls_enabled: bool,
 log_level: String,
 workers: usize,
}

// This is painful
fn main() {
 let config = ServerConfig {
 host: String::from("0.0.0.0"),
 port: 8080,
 max_connections: 1000,
 timeout_secs: 30,
 tls_enabled: false,
 log_level: String::from("info"),
 workers: 4,
 };
}

Every field must be specified. There’s no concept of “default.” If you add a new field later, every construction site breaks. And callers have no idea which values are “important” and which are “just use the default.”

Lesson 7: The Newtype Pattern — Type safety for free

Sun, 21 Apr 2024 13:15:00 +0000

True story: a Mars orbiter was lost because one team used pounds and another used newtons. Same numeric type, different semantic meanings. $327 million, gone.

You’d think we’d have learned. But I still see codebases where user IDs, product IDs, and order IDs are all i64. Where distances are f64 whether they’re meters or feet. Where an email address is just a String that you hope someone validated.

The newtype pattern fixes this. It gives you type safety with zero runtime cost.

Lesson 6: The Typestate Pattern — Compile-time state machines

Fri, 19 Apr 2024 10:28:00 +0000

I once spent two days debugging a production issue where someone called .send() on an HTTP request builder before setting the URL. The code compiled fine — it was a runtime error that only surfaced under specific conditions. In Python. In Java. In Go. This kind of bug is everywhere.

In Rust, you can make it literally impossible to compile. The typestate pattern encodes state transitions into the type system. If the state machine says you can’t send before setting a URL, the compiler enforces it. Not with runtime checks. Not with assertions. With types.

Lesson 5: Iterator Chains Over Manual Loops — Functional Rust

Thu, 18 Apr 2024 16:03:00 +0000

I used to write Rust like I was still writing C — for loops everywhere, mutable accumulators, index variables. The code worked, but it was loud. Five lines to express what should be one. Then I started using iterator chains, and honestly? I’m never going back.

Iterator chains aren’t just syntactic sugar. They’re often faster than hand-written loops because the compiler can optimize them better. Zero-cost abstractions in action.

The Imperative Way vs The Idiomatic Way

Here’s a task: given a list of strings, find all that start with “error:”, strip the prefix, trim whitespace, and collect the results.

Lesson 4: if let and while let — Concise pattern matching

Tue, 16 Apr 2024 08:45:00 +0000

There’s a special kind of code smell that I call “match bloat” — when you write a six-line match statement to handle a single variant and throw an underscore wildcard on everything else. I wrote hundreds of these before discovering that Rust has a better way.

If you’re writing match just to handle one case, you’re doing too much work.

The Problem: Match Bloat

Here’s code I see all the time, especially from developers coming from the previous lesson on Option and Result:

Lesson 3: Option and Result Are Your Control Flow — Stop using sentinel values

Sun, 14 Apr 2024 11:22:00 +0000

I once inherited a C codebase where -1 meant “not found,” 0 meant “error,” and NULL meant… well, it depended on the function. Sometimes it meant “empty,” sometimes “uninitialized,” sometimes “we ran out of memory.” The codebase had roughly 40 unique sentinel values across different modules, and half the bugs were someone forgetting which magic number meant what.

Rust looked at that mess and said: “How about we just… don’t.”

Lesson 2: Borrow Strategically — &T, &mut T, and when to clone

Fri, 12 Apr 2024 14:37:00 +0000

A colleague once showed me their Rust code where every function parameter was String — never &str, never &String. When I asked why, they said “the borrow checker kept yelling at me, so I just take ownership of everything.” Classic.

I get it. The borrow checker can feel like an overzealous hall monitor. But once you understand the borrowing rules — really understand them — you’ll realize it’s not restricting you. It’s showing you a better design.

Lesson 1: Think in Ownership — Not pointers

Wed, 10 Apr 2024 09:14:00 +0000

I spent three months fighting the borrow checker before I realized the problem wasn’t the borrow checker — it was me. I kept thinking in C++ pointers and Java references. Every String was just “data on the heap.” Every function call was “passing a reference.” And every compiler error felt like Rust was being unreasonable.

It wasn’t. I was just thinking about memory the wrong way.

The C++/Java Mental Model (And Why It Fails)

If you come from C++, your brain maps everything to raw pointers, smart pointers, or references. If you come from Java/Python/Go, everything is a reference behind the scenes — you never think about who owns what, because the GC handles it.