This article is part number 8 of the Rust review series.

The Rust Programming Language” is one of the free books that the community has put together to teach the language. The book does a good job in general, but there are some things that could be better. Let’s cover these, but first, some background.

A couple of years ago, right after getting started with Rust, I tried to go through the book’s first few chapters. It all sounded cool… but the first edition of the book moved at a glacially slow pace because it covered things in excruciating detail. E.g. the first chapter I remember was about string formatting, which detailed pretty much all there is on this topic. “Who cares? You don’t need to know all these details upfront to get started.” I thought. So I gave up.

I was pleasantly surprised this time around to find that a second edition exists and that it is much more amenable to read. This new version moves through concepts at a fast pace and delivers the complex details in bite-sized chunks: each piece of a topic is only covered when necessary, and only once the reader has gained enough knowledge of the more simple pieces to make sense of it all.

WARNING: When I read the book three months ago, the second edition was under active development. I see things have changed since then, so my comments below may be stale and not applicable any longer. Similarly, I also went to check the first edition again to justify my first paragraph and couldn’t; bad memory on my side, or did it also change over time?

But while the book is easy to read, the tone of the second edition is… bizarre. At first, and repeatedly throughout the text, the book claims that it doesn’t want to teach programming fundamentals. However, the examples in the book are a mixture of super-trivial details followed by incredibly steep jumps to complex pieces of code. To give you an idea, this is how I felt:

How to draw an own meme

As an example: there is a chapter on testing, which explains the specifics of writing tests in Rust. OK, cool. But that chapter also tries to teach the general rationale behind testing and how tests should be structured, and does so poorly. When you compare super-abstract explanations of engineering principles that basically read like “here is 2+2=4; now go prove P=NP” against trivial examples that are accompanied by line-by-line commentary… well, it’s weird. And some examples, like the ones about closures, feel poorly chosen: the authors could have presented the same concepts with more-realistic and less-convoluted pieces of code. I think the authors have got the right intentions but the wrong balance here. And that’s part of the reason why I didn’t bother with the examples.

But enough criticism. Other than that, the book does a good job of covering the language. At the end of it all, I was left with a good understanding of everything the language has to offer; I know now where to head to, should I need more details. And I feel this is crucial: it’s important to know about all the possibilities of references, traits, lifetimes, threading, etc. before writing real code, or you may easily get stuck in situations you don’t know how to escape.

Finally, I’d say there are a couple of topics that I wish hadn’t been omitted.

The first is more detail on how Rust code actually compiles to machine code. For a language that claims to have zero-cost abstractions, I’d like to know how what I’m writing translates to assembly. E.g. for C++ I’ve got a reasonably good mental mode of how templates work but I don’t have a clue about generics’ inner workings (and their tradeoffs) in Rust. Knowing these details is crucial if your goal is to write highly-efficient code, and Rust claims to fill this gap.

The second, and much less problematic, is a more detailed description of annotations and an overview of those that exist. I’ve noticed the compiler complaining about unused results because certain functions are marked with warn_unused, but I don’t know what the possible annotations are.

TL;DR: If you want to learn rust, start with this book. I recommend following the path I took: a quick cover-to-cover read to learn everything the language offers without paying much attention to the examples or exercises. Then, focus on writing real code and refer back to the book or the API reference manuals to learn anything you need in more detail.

Oh, and by the way: there is also Rustonomicon, which seems both horrifying and exciting—but I haven’t had a chance to read through this one yet.