[steveklabnik]

I am in the middle of working on a second draft of the book. This page is one of the oldest bits of docs, overall, and isn't my best work. It's not _wrong_, I just have very high personal standards. It was adapted from older documentation and was written in the time up to 1.0, where I had a LOT on my plate.

[galonk]

It certainly is _confusing_ if not _wrong_. You silently add "move" to the closure without any mention or explanation (then later say "note that we're copying i" without explaining that you're talking about the "move" keyword).

The bit about Mutex also has a "just type this to fix the problem with no explanation of how or why it works" flavour (although I guess if you already grok mutexes then its use here might be obvious to you).

Not a criticism of the tutorial, but it does something common in Rust tutorials which is really a problem with the language at this point: Rust tutorials always spend a lot of time interpreting Rust's notoriously poor error messages (e.g. "what this message that doesn't mention Sync is trying to tell you is that you need Sync on this type"). That's great when you're doing the tutorial, but as soon as you're on your own man are those errors frustrating.

[Manishearth]

> Rust's notoriously poor error messages

I've actually heard the opposite feedback; Rust's error messages try to be super helpful.

Note that concepts like ownership and Sync are new to most programmers, and it's impossible to explain them in an error message. This is where the extended error messages (via --explain) and the book come in.

The tutorial has this style because Rust espouses catching things at compile time, so the tutorial demonstrates this being done by doing the wrong thing a few times and reiterating why it gave an error.

----

Could you give examples of confusing error messages? I'd love to improve them. The one you mention .... doesn't exist. This (http://is.gd/keukPm) is what that error message looks like, and (a) it mentions Sync, (b) it also mentions that `Arc<bool>` cannot be shared between threads safely.

If you were referring to "So, we need some type that lets us have more than one reference to a value and that we can share between threads, that is it must implement Sync." from the book, the last part about Sync has nothing to do with that error message. If you follow the book, the error message is clear without the context of threads -- `data` was moved into the first spawn() call and the subsequent ones can't use it. One does not conclude that Sync is necessary from this error message, and that's not what the book is trying to say.

This sentence is actually skipping a step, one like http://is.gd/RPNOm4, where the compiler asks you for a Send type (or a Sync type, depending on the exact code). Instead of stepping through this example, it just introduces Sync directly by noting that we're dealing with threads anyway and the reader already knows what Sync/Send are. It doesn't conclude that Sync is necessary from the error message.

> The bit about Mutex also has a "just type this to fix the problem with no explanation of how or why it works" flavour (although I guess if you already grok mutexes then its use here might be obvious to you).

The previous sentence says "for example a type that can ensure only one thread at a time is able to mutate the value inside it at any one time.", which is exactly what a mutex does. Unless you want a lower level explanation which IMO isn't necessary. It could explain locking more though; I'll fix that.

[firebones]

I've found the Rust compiler to provide very useful messages. That said, it does take a certain amount of experience in the language before you grok the terminology and appropriate remedies to overcome some compiler errors. As a beginner, I'd typically open about 5-10 different documentation, blog post, SO and tutorial pages to try to figure out what I was doing wrong. Once I understood the underlying concept, I could go back and understand what the compiler message was telling me, as plain as day. After awhile, I had a strong enough understanding of the borrow checker that I could usually interpret the compiler error messages in a pretty straightforward fashion. But it takes time if you're coming from a non C/C++ language!

If you're learning Rust, I would recommend tracing back every compiler error you encounter to this page [1] to see some other examples and resolutions (if the compiler's suggestions don't make it clear as to what to do). It's the most underrated page in the entire Rust documentation set, and could be the launch point for a lot of teaching and learning. Read the book to start, certainly (and the revisions Steve Klabnik has been making are very, very good), but that error index page is very valuable for the day to day issues.

Rust rewards gumption [2] and perseverance.

[1] https://doc.rust-lang.org/error-index.html [2] https://en.wikipedia.org/wiki/Gumption_trap

[Manishearth]

> you encounter to this page [1]

I love the extended errors. Note that you can just use `rustc --explain <error code>` without opening a web page, but of course it won't be formatted then.

> But it takes time if you're coming from a non C/C++ language!

Ultimately there's little substitute to learning the concepts behind the language :) Error-driven-development is fun, and quite useful once you know the language, but if used as the only way to learn the language it can be problematic. That said, I enjoy using errors to explain Rust concepts -- as long as you explain them. If a new user is hit with a steaming pile of errors you can't really expect them to understand it directly.

I have talked with a lot of folks coming from a non-systemsy background, and sort of have an idea of the things that get confusing (I once had similar problems when learning C++). I'm planning a blog post series (no ETA, pretty swamped with other work :/ ) that teaches both Rust (specifically, the safety bits like the borrow checker) and what's going on under the hood (regarding memory, the stack/heap, etc) using each as a crutch to explain the other in a leapfrog way, to introduce the language and low-level programming to folks coming from languages like JS.

[steveklabnik]

Yeah, this is what I mean. So this was originally written before "move" or even any of the current closure implementation existed. And with so much to do, the focus was on making what existed accurate more than a holistic approach.

Furthermore, almost a year after 1.0, we have a lot better understanding of what people struggle with when trying to learn Rust, so we have a better idea of how to teach it.

Please file bugs for notoriously poor errors. We have put a lot of work into many of them, but there's a lot of ways to go. It seems like most people really like them or really hate them.

[lambda]

  Rust tutorials always spend a lot of time interpreting 
  Rust's notoriously poor error messages

I'm wondering where you got the sense that Rust's error messages are "notoriously poor." Can you expand on that?

I have always found Rust's error messages to be quite good. Of course, they can be hard to interpret occasionally if you don't already grasp the concepts they are referring to. But I don't see any way to solve that in error messages; at some point, you have to learn enough about the language for the error messages to make sense. And occasionally, the suggestion they provide for how to fix the issue isn't the right suggestion, but I don't know if there's a way to always do that without strong AI that understands what you mean. The best you could hope to do is to provide suggestions for all of the possible fixes, though that could lead to some messages that are too verbose to the point of being useless.

I think it would help to provide some examples of error messages you have had trouble with, to help figure out ways to make them better.

[Manishearth]

FWIW, I fixed some of these concerns here: https://github.com/rust-lang/rust/pull/32529

[pcwalton]

> what this message that doesn't mention Sync is trying to tell you is that you need Sync on this type

There's no such error message that I'm aware of.

[nindalf]

Thanks Steve, you're doing great work. Can't wait to read the book once its done!

[steveklabnik]

Thanks! You can follow along with the progress here, if you're interested: https://github.com/rust-lang/book