An alternative introduction to Rust

+1; this feels unhelpfully verbose, and it tries to do too much.

I spent the last two weeks reading the entirety of the 30 minute intro, TRPL, and Referecne, and Rust By Example. My background is primarily Python / Java / JavaScript. I can read but am uncomfortable writing C.

This article touches on mutability, references, stack versus heap, ownership, and lifetimes. It has listings of C and C++ code interspersed with Rust. At one point there are nine tables representing memory layout, with no clear indication of what's changed, and only the first 3 tables even fit inside my browser in their entirety.

I understand what you're trying to get to, but I don't think this is that. I'd appreciate detailed sidebars on how Rust avoids dangling pointers / data races / etc., but not part of the main path immediately following "Hello, world." Systems language folks will readily grok that stuff without exposition on what a stack and heap are, while those of us from higher level languages would get stopped in our tracks and completely bogged down in that morass.

Lifetimes and ownership were the most difficult concepts for me to grok, but I was able to make it through TRPL relatively quickly and come out knowing exactly where I was unclear. Rust By Example helped immensely on that front. I specifically appreciated the destroy_box function on http://rustbyexample.com/move.html, though the entire snippet was quite illuminating.

The examples of lifetime elision on http://doc.rust-lang.org/book/ownership.html#examples coupled with the attempts as manually annotating lifetimes in http://rustbyexample.com/lifetime/fn.html finally made that click.

I'm just one learner, but in my experience TRPL is fundamentally sound. I wouldn't fix what isn't broken. It may not sell Rust in the sense of putting its "best foot forward," but it's concise and it works. When shooting for first impressions, it might be worth focusing on the 30 minute intro or some other document instead. I didn't touch TRPL until I had been sufficiently sold on the language from other venues to commit to learning it.

Edit: But holy shit, Steve, thank you so much for the work and care you're putting into this. Rust wouldn't be where it is without you.

It's still too confusing. Try drawing actual pictures to illustrate the scope/lifetime issues. Talking about addresses on the stack is an implementation detail.

Things to cover:

Basic lifetime concepts in Rust:

   1.  Scopes are nested.
   2.  Variable lifetimes are tied to scopes.
   3.  Unlike other languages, variables can be created
       tied to a scope outer to the one where they are
       created. The user can control this by indicating
       that the lifetime of a variable is the same as that
       of some variable from an outer scope. This is Rust's 
       big innovation.
   4.  A function can create a new object and return it by
       reference if the function explicitly says that the 
       new object has the same lifetime as some parameter.

Basic ownership concepts in Rust:

   1.  There are three kinds of ownership - single ownership, 
       reference count multiple ownership, and thread-safe reference 
       count ownership.
   2.  The reference count ones work like you'd expect.
   3.  Single ownership interacts with the lifetime system in 
       to make it possible to create data structures such as
       trees, with all components single ownership and having the
       same lifetime.
   4.  The "=" operator usually means "move", and when it does,
       the right hand side of the "=" becomes inaccessable.
       (This is type-dependent; some types copy when "=" is used.)
       This preserves single ownership.

Basic data structure concepts in Rust:

   1.  Rust has enums, which, unlike enums in other languages, can
       have data objects associated with them. They're really variant
       records.
   2.  You can declare an enum with a data object as a field in a 
       structure. This creates a structure that contains (really links 
       to) another data object.
   3.  This can be done recursively, so you can create trees of
       structures.  
   4.  You can't violate the rules of single-ownership.  Trees are OK;
       directed acyclic graphs or backpointers are not allowed using
       single ownership.
   5.  There's no "Null". Instead you create enums which have one value
       with an associated data item and one without. 
   6.  Everything has to be initialized to a valid value for its type.

Basic borrowing concepts in Rust:

   1.  You can create temporary references to something with an equal
       or longer lifetime, because the temporary "borrowed" reference
       cannot outlive the thing it is referencing. That's safe.
   2.  You can have one writer (a mutable reference) or N readers 
       (immutable references) at a time.

Basic type concepts in Rust:

   1.  It's complicated.
   2.  There's automatic type inference.  Not just for "let", either.
   3.  Function parameters have to be declared, not inferred,
       except for the special syntax for closures that lets you write
       concise lambda expressions.  This limits how hard the
       type inference system has to work.
   4.  I don't fully understand Rust's type system yet.

Basic safety concepts in Rust:

   1.  All of the above is enforced at compile time.
   2.  The result is memory safety.

Misc. notes:

  - Lifetimes are novel, but not that complex.
  - The type system really is complex.
  - There are generics and you'll need them more often than in C++.
  - The compiler first checks syntax, then types, then borrowing. It does not report
  borrow errors until everything else is correct.
  - There are no exceptions, and proper error handling requires rather verbose code.
  - Have a plan for your variable lifetimes before you start coding, or you end up
  fighting with the borrow checker and losing. 
  - If you think you need "unsafe" in pure Rust code, you're doing it wrong.

Not quite a TLDR, but this is a nice presentation by Lars Bergstrom that assumes more background knowledge:

https://vimeo.com/120512790

I like the new structure much better!

Now, I'm in no way a writer. English isn't even my main language.. So take this next point accordingly:

Unfortunately, I get an even more condescending vibe from this draft than I got from the book. Not as in "I'm an expert and you're treating me like a newbie," but as if I was a kid instead of an aspiring Rust programmer (beginner or otherwise). I wish I could point out -exactly why- I get this feeling, but I'd be lying.

I do think I'm starting to see a pattern, though, that perhaps contribute to this gut reaction. The pace between concept introductions is odd, somewhat erratic. At times, in one line you're talking to a complete novice programmer, and the very next you assume they know other languages and general concepts [1]. Other times, you take some basic knowledge for granted and explains it right after [2]. I know it must be very hard to find the right balance for your target audience, but I found these jumps very jarring. For what it's worth, once you get past the introductions you pick up a more to-the-point-explanations rhythm and that reaction goes away.

[1]: For example, after several paragraphs and two code snippets to introduce the concept of 'variable bindings' in a novice-friendly way, even going as far as (somewhat) explaining what system and functional languages are, the text suddenly assumes I know about program execution and what a control flow structure is?

> As you know, a computer program is executed line by line. At least, until you hit a control flow structure, anyway.

This line was specially off-putting. After all that explanation, the assumption I'd know this made me feel like a kid. But I can only imagine how inaproppriate I'd feel if I didn't know. Given the novice level of the text up to then, the 'as you know' sounds very out of place.

[2]: The very next paragraph, we go over a program with one variable binding line by line. And then, it's assumed I know about scopes. But after that they are explained anyway. I realize this is a way to go over every concept, even if one already knows them, but it feels odd! Both beginner and experts would understand a plain explanation. But this back-and-forth about how to present concepts doesn't work -- for me. It'd make more sense to read straight-forward explanations of what I already know than these "as a programmer, you know that x," mixed with even simpler concepts being introduced as new.

This sounds harsher than I planned -- I'm no writer afterall! But, really, despite these gut reactions, the Rust book is turning into one of my favorites. Thank you for all your work!

I was actually reading the rust lang book for the first time yesterday, specifically the intro to lifetimes that this post is a revision of.

I'm not sure jumping so much into what's going on in the C++ side is a great idea. The section as it stands now covers the important points (with out lifetimes invalidating pointers is easy) without getting too lost. However, I'm already pretty familiar with C++, so the more brief explanation may not be enough for everyone.