Recently I wanted to write a utility for my own use.  I could write it in Python, Perl, C, or any number of other languages, but since Rust is all the buzz these days, I thought I’d give that language a try.

I popped over to rust-lang.org, clicked Learn, and started reading The Rust Programming Language.

Affectionately nicknamed “the book,” The Rust Programming Language will give you an overview of the language from first principles. You’ll build a few projects along the way, and by the end, you’ll have a solid grasp of the language.

TRPL is clearly written for experienced programmers, not people whose first programming language will be Rust.  It doesn’t included in-depth discussion of what a variable is, for example.  The reader is expect to know common concepts.  Sounds like exactly what I wanted.

Unfortunately, it was a frustrating experience.

Typical Programming Language Books

What I expected was:

• First, you learn how to write a “hello, world” program because you always start with that.
• Then you move on to slightly more advanced concepts – how variables work, how control structures like loops and conditionals work, etc.
• Next you get into objects (if relevant) and data structures, and the different choices the language makes.  The standard library’s more common functions are explored – how to open and read a file, for example.
• Along the way, there’s discussion about what makes the language unique.
• Finally, there’s discussion about the tooling and working with bigger projects.

This has been the template for programming language books since forever.  The Rust Programming Language doesn’t take this approach.

Chapter One: Cognitive Burden

Chapter starts with quite a bit of detail about setting up your environment, which is fine but probably too detailed at this stage.  For the vast majority of people, it’s going to be just adding a package with apt or whatever, but I don’t mind the extras so people can get going.

Then it’s off to Hello, world!

fn main() {
  println!("Hello, world!");
}

Great. I am now officially a Rust programmer.

But already we’re running into “we’ll come back to that,” and that’s a big part of my criticism.

When an author says “here’s an idea, which I won’t explain now, just go with it and we’ll come back to it later,” this places a cognitive burden on the reader.  It builds up a debt of unanswered questions that are filled in with placeholders of future promises.  It’s like a “to do” in your mind.

Why is it println! and not just println?  That was my initial question when I looked at the code.  I think nearly every experienced programmer would ask that question.  What’s up with the exclamation point?  It jumps out at you because it’s not a syntax you see elsewhere.  It must mean something important.

The answer is: (1) it’s a macro, not a function, and (2) wait until chapter 20 to find out why.

Grrr…

Structuring lessons to expose concepts in the right order is a vital part of writing a book.  In this case, the answer is correct, but I think a brief explanation of why this is done this way would be helpful.  Particularly because 100% of programmers coming from other languages are coming from worlds where printing something to standard output is a core feature of that language’s standard library.  Saying “in Rust, printing to standard output is a macro” is quite shocking.  And TRPL is written for experienced programmers.

Perhaps a brief comment like:

Wondering why println! is a macro and not a Rust standard library function?  Implementing this as a macro allows Rust to validate the arguments at compile-time instead of run-time.  Malformed printf arguments in C, for example, are a notorious source of run-time bugs.  Rust avoids this.

With that brief blurb, I now understand why Rust does this.  Makes perfect sense.  I can then wait until chapter 20 to learn all about macros, but in the meantime, my curiosity – about something that is so out of the norm that it demands curiosity – is satisfied.  And I gain an admiration for Rust because it does this to avoid bugs.  Instead of a “well, that’s weird” moment and a “ok, I’ll keep it on a mental list and I guess trust the author” burden, I now have a “oh, that’s a good idea” moment.  And I didn’t have to leave the book to google why.

Deep End of the Pool

Next we go on to Cargo…wait, what?  This seems a bit advanced.  And Git.  And TOML.

Here is the second sin – loading up the reader with multiple deviations from the main path.

I once had a sysadmin colleague who was a super engineer and wicked smart, but he took extremely circuitous paths to explain anything.  You’d ask how to add space to a filesystem and 20 minutes later he’d be explaining how modern filesystems are derived from the Berkeley Fast File System which  recognized the rotational nature of spinning disk and hence structured the on-disk data to…c’mon Vincent, just give me the command.

Cargo belongs a few chapters further in.  I want to get a good grasp of Rust the language first before getting into things like “Building For Release”.  I can barely write Hello, World! and we’re building for a release.

I happen to be familiar with git and TOML, but not every dev will be, and now we’re loading up the new concepts.  A good textbook should introduce one concept and explain it well before moving on to the next.

Overload

All right, now we’re on to Programming a Guessing Game in chapter two.  We’re going full-Cargo on this, so there’s some Cargo setup first and creating TOML.  We write some code, with new ideas, such as using std::io, mutable variables, and stacking methods.  We also mention comments, which I think should be at least it’s own section in the chapter but they’re explained in passing.

By the end of the chapter, the cognitive burden is again growing:

• “We’ll be discussing this concept in detail in the “Variables and Mutability” section in Chapter 3″
• “Chapter 4 will explain references more thoroughly.”
• “Chapter 6 will cover enums in more detail.”
• “You’ll learn about recovering from errors in Chapter 9.”

There’s several more of these but you get the idea.

Maybe our second program shouldn’t include tons of new things we haven’t covered yet?  This chapter’s code includes:

• variables
• mutation
• the standard library
• method stacking
• Result
• more advanced println!
• references
• enumeration
• how to read compiler output
• SemVar
• reproducible builds
• Cargo.lock
• the Cargo registry
• the rand crate
• match

…and more.

It’s a lot all at once.

In contrast, here are are the first few programs in The C Programming Language:

• program #1: stdio, printf
• program #2: comments, integer variables, while loop, printf with variables
• program #3: the for statement
• program #4: floats, #define
• program #5: getchar/putchar
• program #6: long, the ++ operator
• program #7: if/else, the || operator

As you can see, concepts are introduced a couple at a time, in short programs.  This is the right approach.

I read a little more, but it was late.  I’ll continue on, and I’m sure I’ll get a lot out of the book.  I just wish it was written in a more user-friendly way.

How to Learn a Programming Language

The real way to learn any programming language is to write code.  I read a book to get the main concepts, and then try implementing something.  Things don’t compile or work right.  Sometimes it’s simple syntax I’m not used to (that exclamation point after println!), and sometimes it’s concepts (variables are immutable).  You fix and rip out and replace.

You also read code.  It’s easy to write non-idiomatic code in a language by carrying over concepts from whatever language you come from.  My early Python programs were Perl masquerading as Python, just as a lot of my early Java code was really C wrapped in a couple objects.

So ultimately, the utility value of a book is limited.  No matter how good it is, you can’t read a book and the immediately go write masterful code in that language.

I’m sure the author of TRPL didn’t get paid for his work, so we should be grateful it exists regardless of its warts.  And it does have the wonderful quality of being free.  Apparently many in the community like it, and you may very well like it.  But it’s the kind of programming language book I find unnecessarily burdensome to read.

raindog308

raindog308 is a longtime community LETizen, technical writer, and self-described techno polymath. With deep roots in the *nix world, he has a passion for systems both modern and vintage, ranging from Unix, Perl, Python, and Golang to shell scripting and mainframe-era operating systems like MVS. He’s equally comfortable with relational database systems, having spent years working with Oracle, PostgreSQL, and MySQL.

As an avid user of LowEndBox providers, raindog308 runs an empire of LEBs, from tiny boxes for VPNs, to mid-sized instances for application hosting, and heavyweight servers for data storage and complex databases. He brings both technical rigor and real-world experience to every piece he writes.

Beyond the command line, raindog308 has a life-long love of German Shepherd Dogs, high-quality knives, target shooting, theology, tabletop RPGs, playing guitar, and hiking in deep, quiet forests.

His goal with every article is to help users, from beginners to seasoned sysadmins, get more value, performance, and enjoyment out of their infrastructure.

You can find him daily in the forums at LowEndTalk under the handle @raindog308.