Here's my suggestion that I strongly believe could help Rust's (or any platform's for that matter) adoption:
There should be a list of somewhat larger projects (similar to the sample apps for Cocoa https://developer.apple.com/library/mac/navigation/index.htm...) maintained by people who actually understand the language. For me, and I imagine a lot of other people, the hardest part about learning a new language/platform is getting from the stage where I understand the syntax and APIs to getting somewhat proficient with it and being able to make informed decisions about how things should be done in that language.
A lot of times, when I look at some open source projects to learn from, I'm left with the impression that the author might not have really understood what s/he's doing and that really increases my frustration with the platform. A list of canonical projects would prevent this.
I'm aware of Servo but I feel that Servo is a.) too large of a project for a Rust n00b to learn from b.) it's not always up to date WRT to the language version and the best practices.
Alternatively, this could also be a list of 3rd party projects blessed by the Rust people as good projects to learn from.
While it might seem like a waste of time, I feel like this would e.g. reduce the number of people needing help on IRC or the mailing list so it might actually save time.
I completely agree. 9 times out of 10 I can pick up a new language, understand the syntax, but how to idiomatically structure a project is a completely different thing. Most of the time I would rather have the latter than the former - I can pick up most syntax from its actual use.
steveklabnik, along these same lines, I've come across the claim that things like map, reduce, fold, etc., are not idiomatic Rust. But nothing about why or why not that might be true. That kind of guidance would be valuable, especially since Rust borrows so many concepts from functional languages.
I will certainly say that Rust is young enough that idioms are still forming, so beware of those who say anything is strongly idiomatic. Except four spaces, no tabs. That's _incredibly_ so. ;)
But yes, as they develop, I'll be encouraging the use of idioms directly in the documentation. My years of Ruby make me a big believer in developing and following idioms.
Oh, one last thing about that: iterators are way better than explicit loops in Rust, because loops have to do bounds checking, but iterators don't. So generally, iterators are not just better stylistically, but also performance-wise too.
> because loops have to do bounds checking, but iterators don't.
They still have to check something to know when to stop iterating, though, don't they? You may have traded a bounds check for a dynamic dispatch or some "is done" check, but there's still some conditional logic each iteration isn't there?
That is, "an iterator" is an object that has a next method yielding an optional value, with a missing value indicating the end of iteration. This is conventionally used statically dispatched, and the next method will normally be inlined, so the compiler can optimise it well.
(In particular iterators over simple data structures like vectors optimise to the same code as the equivalent in C/C++, modulo one small bug where LLVM doesn't yet fully understand the nonnullability of Rust's references.)
pcwalton or someone else who understands the issue more deeply here, but my current understanding is this:
Imagine we want to print out every single element of a `Vec`, Rust's growable array type. Here's the code with a loop:
fn main() {
let v = vec!(1, 2, 3);
for i in range(0, v.len()) {
println!("Number {}", v.get(i));
}
}
This of course, has to check that it's only iterated the maximum number of times. The check I'm referring to, though, is in `v.get`. That has to do a bounds check on the array. If we use the iterator version...
fn main() {
let v = vec!(1, 2, 3);
for i in v.iter() {
println!("Number {}", i);
}
}
Now we get each element out of the vector. No more bounds check!
The other replies explained the situation, but for the curious here's Rust's basic code for slice iteration: https://github.com/rust-lang/rust/blob/master/src/libcore/sl... (unfortunately buried in some macros). `if self.ptr == self.end` is where the guarantee is made, then the offsets are done unsafely. The other branch in that function is optimized away statically.
Bounds checking is different from the conditional checks in something like a loop. It's the logic that prevents you from accessing memory that isn't yours. If you have an array arr of length 5 in Java, if you do arr[10] you get an IndexOutOfBoundsException because you're not allowed to do that. If you did the same thing in C, you might get some data which is unrelated to your array, or perhaps a segfault.
So when you you loop over an array, your loop conditional makes sure that your index hasn't indexed out of bounds, in addition to the bounds checking that is performed when actually indexing the array. So you in a sense pay a double price for the same assurance. (This is modulo compiler optimizations.)
Rust has to guarantee memory safety (I guess Java makes the same promise). This means that you have to have bounds checking for array indexing, lest you index out of bounds of some array and get killed by the operating system, if that memory happens to be outside of your process' "turf". You can't eliminate that in general (or; it's hecka hard), but you can probably encapsulate things like iterating over data structures like arrays, vet the code, and say that "this thing loops from 0 to the length of the array minus 1... I swear on my mother's future grave that it is safe to turn off bounds checking for array indexing here." (The way they do it in Rust may be more rigorous than this, for all I know!)
> I swear on my mother's future grave that it is safe to turn off bounds checking for array indexing here." (The way they do it in Rust may be more rigorous than this, for all I know!)
The hard part about doing that is that it's only safe if the array is guaranteed not to be mutated during the loop. Rust enforces this through its borrow checking system.
Thanks for the suggestion. Now that Rust is actually starting to get some 'somewhat larger projects,' I think this is a great idea. And after 1.0, that list will explode pretty shortly.
Fair enough. You probably want to make sure that you have something like this before people start writing larger projects in Rust but write them the same way they would write C++. Eventually, they would hit some wall and complain about Rust as whole even though it's not really Rust's fault.
Mozilla's pcwalton wrote and maintains sprocketnes, an NES emulator written in Rust, which seems like a good example of a practical project with a well-defined scope: https://github.com/pcwalton/sprocketnes
I'm very excited to hear this. Rust is a very promising language, and having good documentation really helps make the difference. I actually got a lot out of the tutorial for Rust when I read it, but there were a number of things that were out of date, and others that weren't covered at all. Rust for Rubyists was also a great guide when I poked through it a while back.
I think one of the sources of success for Golang is its "hit the ground running" approach which takes you from zero to hacker in a short amount of time. Rust is considerably more advanced than Go, but there's no reason that it can't adopt a similar attitude of pragmatism and real-world applicability (although its libraries might lag behind Go's). Having first-rate documentation is a huge step in that direction and a very promising development.
> I think one of the sources of success for Golang is its "hit the ground running" approach
Agreed! One of the weird things about Rust is that it's been open source since the beginning, where languages like Go and Swift have been closed for years before having their first release be very polished.
Rust will get there. Like most things, it just takes time and sweat.
2012 was just the first 0.1 release, it was public before that. Also, Rust is doing more interesting/experimental things than Go with significantly more iteration and change.
Can confirm, I've been involved in Rust since 2011 and Mozilla at large began talking about Rust (publicly, though without great fanfare) in 2010.
Furthermore, saying that Rust has been worked on "since 2006" is misleading. From then until 2009 it was just the work of one man idly tinkering in his free time, hardly a serious project.
If you are building a new language with serious ambitions for usage, you should really take a look at how well the Rust community has turned out to be. The "Buzz" you experience around the language is largely fueled by lots of enthusiasts - e.g. hop on the IRC channel at any time of day and get help. There are no dumb questions, especially about changes that happened in the mainline 2 days ago.
Barriers for committing to Rust itself are very low. Also, they aggressively moderate their spaces according to their CoC. A few days ago, I asked a rather picky question on their subreddit and was quite surprised how on-point and serious the answers were. Given that the topic had the potential for some trolling, it was surprisingly calm.
It's really a community I am happy in.
Edit: I got a bit excited. Obviously, the point of the whole thing is: Mozilla investing into Rust docs seriously and Cargo really shows that this is not an lab language anymore.
Great job Steve! If you don't have them yet, get a copy of Strunk and White's "The Elements of Style" and Kernighan and Ritchie's "The C Programming Language". I'd love my Rust documentation to have the same level of conciseness and clarity.
Fun story: I was actually accepted into English grad school, but turned them down when they changed their tune about the cost of tuition. I already own a copy of both books. ;)
I'm working on my first non-trivial system with Rust right now, and I'm finding that the learning curve related to the borrow checker and lifetimes is rough. I'd liken it to macros in Common Lisp, but not quite as a cliff as monads.
In other words, I would like to ask that a substantial amount of your time in documentation at some point be pointed at the lifetime & memory system, as it is, IMO, the really unusual and hard part of Rust (As well as the whole freaking point of it too! ;)).
Yes, as you mention, the lifetime system is the big issue for newbies in Rust, and also a large part of the point! Revamping those guides is high-up on the TODO list.
I also suspect that lifetimes are one of those features that people might say, "I learned Rust, and I don't code in it, but learning about lifetimes improved my code in $DAYJOB_LANGUAGE." Just like how I think Haskell improved my ability to program in a variety of other languages, but I don't really write Haskell anymore.
This topic would be well served by something like "katas." A series of code samples that look (to the noob) like they should compile, but don't. The series of samples would be chosen to walk the learned through the surprises in pedagogical order.
Actually, that's my preference too. But for certain topics, even after you grasp the principles, there are certain things that are going to surprise you until you get more experience. You can identify these in advance and find they will surprise most learners. So the kata approach is supplementary, kind of like well chosen exercises in a good textbook.
I left Balanced a few weeks ago. I really loved the team, the product, and the work, but I couldn't stand living in San Francisco. I wasn't really doing development work at Balanced, so remote didn't make a whole lot of sense, either. I really want to dis-associate my work requirements from time and space, rather than need to be physically present at an office most of the time. Sometimes, things just don't work out, even when everyone involved wants them to. I still hang out in IRC and even answer questions from time to time.
Fantastic. Keeping the tutorial up-to-date with the language and of high quality is just about the best possible thing you can do for documentation.
Nothing puts me off from a language or system quicker than clicking through to a tutorial that is either (a) extensive but 2-3 versions out of date or (b) hopelessly cursory ("here's 2 pages of neat stuff, see you later").
Can't wait. I played around with Rust when it was in 0.9 and 0.10, but wound up falling off the wagon around then. Stuff was changing too much for me to keep track, and the documentation wasn't always the best. I'm really, really looking forward to 1.0 and better documentation!
If the documentation will be on a hosted site, I would recommend adding the ability for supplemental usage examples of the API provided by the community. Comments on php.net's documentation site and on apidock.com have been helpful for me in the past. Obviously, user usage comments are not always helpful, but sites sort the comments based on what other users find helpful. In my opinion, having the primary documentation with supplemental community supplied usage examples is the best way to do documentation.
It's been a while since I used PHP, but many of those examples are _very_ bad, and encourage very poor practices.
I plan on having examples built-in with the documentation for everything, but actually approved by the team, rather than just as comments. They'll be much higher quality that way.
One of the things I love about Go's documentation is that all examples are runnable in the Go Playground, right there, inline. You can take an example, modify it, and see how things change. Rust would benefit greatly from that same functionality.
It also forces documentation to be up-to-date; one of the reasons I selected Go over Rust a year ago (besides more mature libraries and better documentation) was the fact that Rust seemed to be rapidly changing.
I don't disagree on PHP.net's user supplied examples being horrible at times. I thought that an example voting system would help regulate bad examples. Team approved examples could also be excellent. Does that mean users could supply examples and then moderators would approve the examples?
I wish you the best luck with the new rust documentation and have well placed high expectations for what you will likely do with it.
To elaborate, in contrast to the official tutorial. The trick it plays on you, by hiding most of the list, is really nice when you first land on the page.
I guess I like the bite sized chunks and the organization by concepts.
Although, I never know when there is more info about the current section under the fold.
There should be a list of somewhat larger projects (similar to the sample apps for Cocoa https://developer.apple.com/library/mac/navigation/index.htm...) maintained by people who actually understand the language. For me, and I imagine a lot of other people, the hardest part about learning a new language/platform is getting from the stage where I understand the syntax and APIs to getting somewhat proficient with it and being able to make informed decisions about how things should be done in that language.
A lot of times, when I look at some open source projects to learn from, I'm left with the impression that the author might not have really understood what s/he's doing and that really increases my frustration with the platform. A list of canonical projects would prevent this.
I'm aware of Servo but I feel that Servo is a.) too large of a project for a Rust n00b to learn from b.) it's not always up to date WRT to the language version and the best practices.
Alternatively, this could also be a list of 3rd party projects blessed by the Rust people as good projects to learn from.
While it might seem like a waste of time, I feel like this would e.g. reduce the number of people needing help on IRC or the mailing list so it might actually save time.