RWIB Mission 6: A Better Example

[brson]

Link.

Come up with a new example that fits in the same space and exemplifies
the Zen of Rust. This is a newb's first impression of Rust and it
needs to be breathtaking.

Consider that we might have multiple examples serving different
purposes and put them on a carousel.

[mdinger]

The best analysis of front page examples I've seen is listed here. It's well worth looking at.

[lambda]

As mdinger mentions, I wrote up my thoughts on examples earlier; and I had done that research with the intent of proposing some front page examples, which I then didn't get around to. That said, I am still interested in the project; I have several ideas for examples, and just need to flesh them out.

As I proposed earlier, I think it would be best to have several small to medium sized examples, each focusing on a particular feature, rather than trying to have one be-all and end-all example. I think it's too hard to have a 20 line example that shows off all of what Rust is, and anything much longer will be too much to take in at once. Rather, I liked Scala's approach of having a few feature bullet points, and each one show an example, though I would prefer to have one on display on the first load rather than having to click through to see any example.

One sticking point I ran into when trying to write up some examples is that many of them require cargo or other things you can't use on Playpen. I think that it might be OK to have only some of the examples be runnable, while the others are just plain text that you can run if you download and install Rust and Cargo. Those that can be run on Playpen should be, but I think it's OK to not constrain ourselves that way.

Here are the current bullet points of Rust features on the front page; I am thinking of trying to write one example of each:

• zero-cost abstractions
• move semantics
• guaranteed memory safety
• threads without data races
• trait-based generics
• pattern matching
• type inference
• minimal runtime
• efficient C bindings

I think it would also be good to list Cargo, and how easy it is to use a fairly extensive ecosystem growing in Cargo.

For "zero-cost abstractions", it would be nice to embed something like the compiler explorer to show an example of using iterator combinators that compile down into the equivalent of a for loop.

For pattern matching, I really loved this example that Felix wrote in Mixing matching, mutation, and moves in Rust:

match (x % 10, x % 100) {
    (1, 1) | (1, 21...91) => "st",
    (2, 2) | (2, 22...92) => "nd",
    (3, 3) | (3, 23...93) => "rd",
    _                     => "th"
}

I have some thoughts on the other examples that I will continue to flesh out over the next few days.

Does this sound like a reasonable direction to go in with the example? We will of course still need to pick the example that is displayed by default, but I think that with several examples, each of one major Rust selling point, there's a lot less desire to try to cram too much into one small example.

[alilleybrinker]

Nice analysis @lambda. I agree that slideshows are probably not the way to do, but perhaps a small collection of examples, each of them accessible via some sort of selector (and with one of them shown by default). Each example should also have a link to something explaining the major feature(s) being shown off, probably from the Rust book.

As far as what sort of thing can be used for each of the major features identified above, here are some thoughts:

• Zero cost abstractions: I like the idea of showing off iterators, as they are one of the most common abstractions in Rust code, and they nicely embody this particular design goal.
• Move semantics: This one is difficult, because there is a question of how much we want to include. We can go all out and make it about how everything is moved by default, unless it implements Copy, or as simple as showcasing what a move is in Rust. I am not sure here. If it's something about Copy it could be along the lines of defining two structs, both containing an i32, one of which implements Copy while the other doesn't, along with an example assignment for both of them.
• Guaranteed memory safety: The first thing to look at here is exactly what is meant by memory safety. Per the Rust language reference, Rust promises that no code will do the following, which is guaranteed by the compiler for safe code, and assumed to be checked by the programmer for unsafe code. Any example should likely showcase the inability to do any of these three things.
  • Dereference a null/dangling raw pointer
  • Read undef (uninitialized) memory
  • Break the pointer aliasing rules with raw pointers (a subset of the rules used by C)
• Threads without data races: There is a lot of good stuff to work with here, with a lot already written about Rust's excellent systems for concurrency. We can likely build off prior work quite easily.
• Trait-based generics: Once again, it should be pretty easy. Likely best to take a trait that already exists, define a struct and implement that trait for that struct, and then use a primitive type and the struct in a function provided by that trait. Add would be a pretty straightforward one.
• Pattern matching: I like your idea, and can't think of anything better.
• Type inference: Lots of good options here. We likely want to make it clear that types can be inferred even in a lot of complicated places, and that types are only mandatory in function signatures (or where there is an ambiguity that can't be resolved without an annotation).
• Minimal runtime: I am not sure this can be shown in a static code example. This may be something best left to the book.
• Efficient C Bindings: C bindings are important. Rust's ability to very easily interoperate with C code is a major selling point. We can likely adapt something from the book here.

All in all, I think this is a solid collection of example ideas that should nicely showcase the strengths of the language for newcomers.

[brson]

Rather, I liked Scala's approach of having a few feature bullet points, and each one show an example, though I would prefer to have one on display on the first load rather than having to click through to see any example.

This is a good idea. The only qualm I have is that if we use the feature list to link to examples then we probably can't also use it as planned to link to related blog posts (the mixed types of links would be too intuitive).

[lambda]

This is a good idea. The only qualm I have is that if we use the feature list to link to examples then we probably can't also use it as planned to link to related blog posts (the mixed types of links would be too intuitive).

My thought was that each example could also include a little bit of explanatory text, which could include the appropriate links, rather than all of the explanatory text in comments. I'll draft up a PR for the front page with a couple of examples of what I'm thinking about.

[alilleybrinker]

@lambda perhaps something akin to the install page in structure, with a small explanation and links to accompanying materials in a column on the left, and executable example code from the playground on the right.

[brson]

I'm open to having multiple examples on some kind of carousel, with one showing up by default. I don't think we should try to get one for every bullet point, just because it's so ambitious we probably won't get there. Good idea using the bullets to come up with themes.

Let's try to get people to come up with simple examples for each of the bullets and see where it goes. I'll make a reddit post.

[brson]

https://users.rust-lang.org/t/soliciting-multiple-new-examples-for-rust-lang-org-homepage/3676

[brson]

After we add logos to the front page we're probably going to end up with the content extending just slightly below the fold for a lot of viewers, which is pretty much the worst scenario (rather have everything above or lots of content below). So I suggest that we need the example to be even fewer lines that it is currently.

[dumindu]

Please add more examples which are friendlier to new users

1. after hello world and data types

   use std::io;
   
   fn main() {
       let mut user_input = String::new();
       io::stdin().read_line(&mut user_input)
           .expect("Failed to read line!");
   
       println!("Hello, World.\n{}", user_input);
   }
   

2. after structs and trails

   struct Player {
       first_name: String,
       last_name: String,
   }
   
   impl Player {
       fn new(first_name: String, last_name: String) -> Player {
           Player {
               first_name : first_name,
               last_name : last_name,
           }
       }
   
       fn full_name(&self) -> String {
           format!("{} {}", self.first_name, self.last_name)
       }
   }
   
   fn main() {
       let player_name = Player::new("Serena".to_string(), "Williams".to_string()).full_name();
       println!("Player: {}", player_name);
   }
   

and etc. Also please order docs properly, new users learn about borrow and checker before basics of structs, vectors and etc. This will confuse the absolute new comers.

[brson]

Thanks for the suggestions @dumindu. You're first example might make a good replacement for the current one.

[dumindu]

let me repeat https://users.rust-lang.org/t/soliciting-multiple-new-examples-for-rust-lang-org-homepage/3676/34 in here.

This might not be the right place or the right time, but I would like to suggest a new layout for Rust main page.

1. Top:
   Rust Logo and links for menu items (doc, forum, download, contribute/help, hamburger icon for other menu items)
2. Next
   Special graphs(random/list with link under the graph for more details) and intro (Rust is a systems programming language that runs blazingly fast, prevents segfaults, and guarantees thread safety.)
   Graphs ex http://thoughtram.io/rust-and-nickel/#/11, graphs in https://medium.com/@robertgrosse/my-experience-rewriting-enjarify-in-rust-723089b406ad#.dcpoie6lo etc
3. Examples
   Feature list, on click right side code/video getting changed.
4. Crates and areas uses Rust
   short intro to crates, side crate downloads count & crate count
   Links with/without images for pages like xi editor, hyper, nickel, Piston, arewewebyet and etc.
5. Users/ Friends of Rust
6. bottom
   links for fb, youtube, twitter, github, stackoverflow, blog and etc.

Thanks