Rust should have a lower learning curve

[aturon]

Overview

Rust offers a unique value proposition in part because it offers a unique feature: its ownership model. Because the concept is not (yet!) a widespread one in other languages, it is something most people have to learn from scratch before hitting their stride with Rust. And that often comes on top of other aspects of Rust that may be less familiar. A common refrain is "the first couple of weeks are tough, but it's oh so worth it." How many people are bouncing off of Rust in those first couple of weeks? How many team leads are reluctant to introduce Rust because of the training needed? (1 in 4 survey respondents mentioned the learning curve.)

Here are some strategies we might take to lower the learning curve:

• Improved docs. While the existing Rust book has been successful, we've learned a lot about teaching Rust, and there's a rewrite in the works. The effort is laser-focused on the key areas that trip people up today (ownership, modules, strings, errors).

• Gathering cookbooks, examples, and patterns. One way to quickly get productive in a language is to work from a large set of examples and known-good patterns that can guide your early work. As a community, we could push crates to include more substantial example code snippets, and organize efforts around design patterns and cookbooks. (See the commentary on the RFC thread for much more detail.)

• Improved errors. We've already made some big strides here, particularly for ownership-related errors, but there's surely more room for improvement.

• Improved language features. There are a couple of ways that the language design itself can be oriented toward learnability. First, we can introduce new features with an explicit eye toward how they will be taught. Second, we can improve existing features to make them easier to understand and use -- things like non-lexical lifetimes being a major example. There's already been some discussion on internals

• IDEs and other tooling. IDEs provide a good opportunity for deeper teaching. An IDE can visualize errors, for example showing you the lifetime of a borrow. They can also provide deeper inspection of what's going on with things like method dispatch, type inference, and so on.

Projects

Documentation

• The new book, which is being written by @steveklabnik and @carols10cents.
• The Rust Cookbook
• The rustdoc revamp (very early stages), which should help make crates more accessible.

Language improvements

• Language ergonomics/learnability improvmenets

Compiler improvements

• Currently no sustained work on further improving error messages, but this is an area we should revisit.

Tooling improvements

• The IDE initiative

Data points

• http://members.iinet.net.au/~ideasman42/blog/learning_rust.html

[rjammala]

Also, please consider adding as many screencasts as possible to http://intorust.com/
I found it very useful and instructive.

[Selhar]

I'm currently learning rust, and what has worked for me was using the rust book and docs as one big reference material, since the book is far too dry to read from cover to cover. "Rust essentials" is better at teaching rust as a language instead of a reference material, however it lacks in depth at times.
Using "rust essentials" as a guideline, rust book as a reference material and project euler / hackerrank's 30 days of code exercises has been the most effective method for me.

One other thing that has been problematic for me as a beginner is rust's IO, it was quite difficult to figure it out how to parse input into other data types, finding a snippet that works is fairly easy but understanding how it works was nightmarish. Specially for beginners that can be a let down, as most exercises expect you to use IO effectively.

[steveklabnik]

@gregorygoncalves the new book has a whole chapter on IO, covering env variables, command-line arguments, and files: http://rust-lang.github.io/book/ch12-00-an-io-project.html

[aturon]

Another potential area of focus: rustdoc. Since that's the way a lot of people encounter APIs, making rustdoc's output as clear and useful as possible is extremely important. See this thread about Rocket for an example.

If anyone listening is interested in taking on rustdoc work, please let me know!

[steveklabnik]

Agreed; I have some thoughts and vague plans here, if anyone is interested in working on it, please contact me.

…

On Feb 6, 2017, 16:10 -0500, Aaron Turon ***@***.***>, wrote: Another potential area of focus: rustdoc. Since that's the way a lot of people encounter APIs, making rustdoc's output as clear and useful as possible is extremely important. See this thread (https://news.ycombinator.com/item?id=13582404) about Rocket for an example. If anyone listening is interested in taking on rustdoc work, please let me know! — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub (#3 (comment)), or mute the thread (https://github.com/notifications/unsubscribe-auth/AABsigvwONeZMfgT7Om5WJbuvEz9SbMbks5rZ4xigaJpZM4Krwnl).

[sophiajt]

@steveklabnik - let's chat. I'm actually meeting with @alexcrichton to brainstorm in an hour and a half. Putting some notes together now.

[burdges]

I'd think the module system concerns mostly boils down to error messages, i.e. you might want implicit modules not so much because you want people to use them but because you need the compiler to examine the source files that lack a mod directive so that it can say "You wrote my_mod::foo() but you forgot to add mod my_mod;."

[mbrubeck]

Errors caused by linking to multiple versions of a crate are a very common source of questions on IRC. For example, a project depends on crate A, which depends on serde 0.8, and also crate B, which depends on serde 0.9. Passing types from crate A to functions from crate B doesn't work, because they implement the wrong versions of the serde traits.

Solving this usually involves multiple steps:

1. Recognize the cause of the problem. Improved compiler diagnostics have helped this somewhat, but there still seem to be mysterious errors in some cases. (Two different versions of a crate interacting leads to unhelpful error messages rust#22750)
2. Examine Cargo.lock to see which crate(s) have multiple versions being built. (Really this only matters if these crates are "public dependencies" in the Cargo should understand distinctions between public/private dependencies cargo#2064 sense.)
3. Work backward through the dependency graph to see which direct dependencies depend on different versions of the same indirect dependency. (Tools like cargo-tree can make steps 2 and 3 easier.)
4. Search crates.io to see if there is a set of versions of these direct dependencies which have compatible constraints on the indirect dependencies.

If step 4 finds a viable set of dependency versions, then the solution is to edit Cargo.toml to specify those versions. If not, then a possible next step is to check the lagging crates' repositories to see if there are any forks or branches with updated dependencies, or create such a fork if not.

All of this process is difficult both to discover and to execute. It would be useful to automate as much of it as possible, for example by adding logic to Cargo to find and suggest sets of crate versions that are likely to "play well" together. This would likely require some imperfect guessing, though additional metadata like rust-lang/cargo#2064 could improve the accuracy.

[nox]

Errors caused by linking to multiple versions of a crate are a very common source of questions on IRC. For example, a project depends on crate A, which depends on serde 0.8, and also crate B, which depends on serde 0.9. Passing types from crate A to functions from crate B doesn't work, because they implement the wrong versions of the serde traits.

This wouldn't happen if cargo didn't update all point releases for no reason whenever it can, settling on trying to find a common compatible version of all crates.

This also wouldn't happen if people properly did breaking bumps in their project for breaking bumps in their dependencies, but apparently not everyone agree that this is what should be done.

[mbrubeck]

This wouldn't happen if cargo didn't update all point releases for no reason whenever it can, settling on trying to find a common compatible version of all crates.

It wouldn’t happen then when updating an existing project, but it would still be an issue when creating a new project, for example if one crate has released a version that uses serde 0.9 while another crate is still using serde 0.8 in its latest release. Someone creating a project that calls generic functions from crate A using types from crate B can’t simply choose the latest release of each from crates.io.

[sfackler]

settling on trying to find a common compatible version of all crates.

This is an NP-Hard problem. There's an open issue on Cargo for a year or two to integrate with an SMT solver but no one has stepped up to actually do the work.

[aturon]

Here's a nice post talking about some roadblocks to learning Rust today.

[Manishearth]

Code isn't even documented, you have to search what happens in block of text

The block of text contains the relevant bits of code, though. The idea is that you read the text and refer to the full code, not the other way around.

What you're looking for is http://rustbyexample.com/ . The book isn't intended to be everything at once.

[aturon]

@RUSshy It'd be great to leave this feedback directly on the resources, rather than on this tracking issue (which is used for broader discussion about learning curve goals).

[carols10cents]

oh sorry! Can you link me the resources page please ? is it the forum ?

@RUSshy The repo for the new book is here: https://github.com/rust-lang/book and rustbyexample.com's repo is here: https://github.com/rust-lang/rust-by-example

computer isn't a book, it is meant to be interactive

NoStarch is going to be printing the new book, though, so it will be a book, and we're writing it with print primarily in mind.

[aturon]

Added the Rust Cookbook.