Thoughts about integrating testing into the Rust documentation

Thank you for caring about the book! I really appreciate threads like this. :heart:

So, way back when, I actually did this, with my "Rust for Rubyists" project. I think this is a very valid approach for a book, but I'm not sure it's a valid approach for the book. Here's why:

TRPL has some odd constraints, given that it's official documentation. Or rather, as a member of the core team and doc team lead, I feel that the book has some constraints. Here's a non-exhaustive list:

  • The book is the primary way that new users learn Rust from the Rust project itself. That means that it cannot make assumptions about the backgrounds of users coming to Rust, unless we as a project decide that we want to make assumptions about Rust programmers. And we've decided that we explicitly want to be welcoming to a large background of programmers.
  • Because we cannot make this kind of assumption, we also can't assume that people will be familiar enough with certain constructs to just gloss over them right away. Another way of putting this is "forward references should be minimal."
  • We should not assume that everyone learning Rust is a professional developer, and skilled at related-but-not-exactly-programming tasks like testing.
  • While testing is useful in Rust, TDD is not something that we can assume that people want to do, know how to do, or find to be a valid approach.

So this is why I didn't start TRPL out with testing stuff. While testing is useful and I love it, the point of the book is to teach Rust, not to teach testing. A "test-first" approach for the book would lead people to assume that Rust is often test-first, which I think is actually fairly misleading. And Rust is missing several important things that make a test-first approach work well, like mocking.

Beyond that, you can't teach testing as literally the first thing in Rust. Teaching the output of cargo new, with the smallest, idiomatic setup for tests, would include:

  • functions
  • attributes
  • modules
  • conditional compilation
  • macros
  • use

It's non-trivial. That's why I prefer to introduce testing later, after you have a basic handle on the language. We can show you something that's more idiomatic, without distracting you by saying "ignore all this stuff."

In other words, I find "Time to learn Rust! Okay, before we do that, let's talk about testing. Ignore this Rust code, you'll figure it out" to be not a great start for the book that TRPL is trying to be. That doesn't mean another book might not work that way!

With this example, you've almost doubled the lines of code, and introduced even more new features, like lifetimes. And, I would argue that this is a very, very brittle test. I'd flag it in code review if this were a "real" project.

The purpose of the Guessing Game is to bootstrap someone's understanding of Rust if they're a "dive in heads first" kind of person. Making the code "production quality" isn't a goal. If it were, I'd have written some bits differently. Specifically to make it testable. But doing so introduces a ton of extra concepts that distract from the "here's a fairly direct port of a classic coding example, see, Rust isn't that hard or weird!" aspect of it.

The length here explodes as well. The book is already very long. Making everything TDD would make it much, much longer.

Another practical consideration

The book is too far along to re-work it from the ground up again. The initial chapters are basically locked-in at this point. I have already written two books on Rust and am going through this ground-up re-write right now, at some point, I would like to do something else with my life :smile: Re-working the book Yet Again would destroy all of this forward progress; doing it right would be a complete re-write. And a complete re-write would be Yet Another Book.

In conclusion

So yeah, I appreciate the idea here, and the thought you've put in. I would love to see a "test-driven Rust" book. But we cannot change TRPL in this way.

8 Likes