14 ms·

Rust Guide

• axaxs 12y ago
  Honest initial impressions from my quick glance. This guide is confused. It reads at times like an informal conversation... lots of exclamations. That's pedantic, the real confusion comes from the target audience. As a programmer, I want as little cruft as possible. Get me to examples and how this differentiates from C. As a non programmer, teach me the basics of types and logic. From that thought, it's failing at both. As a programmer, stop talking to me informally and redefining types as one liners. As a newbie, you're explaining basic shell constructs as if I don't know, then trying to sum up strings in a one liner. I know it's an early draft, and I know Steve is an awesome dude. My advice - figure out your audience or else break into two guides. Be terse with me, be overly explanatory to a beginner. This now seems to sway on both sides of that line, and likely will frustrate both groups.
  • buster 12y ago
    If you want more details, less cruft, you probably like to read the Manual: http://doc.rust-lang.org/rust.html http://doc.rust-lang.org/rust.html The Guide is fine as a tutorial and where does it not teach the basics? So your impression is definitely not mine. "Stop talkting to me informally" is also very subjective. I very much prefer the informal way.
    • ash 12y ago
      Looking forward to reading "Rationales and design tradeoffs" section. But it's still not written: http://doc.rust-lang.org/rust.html#appendix:-rationales-and-design-tradeoffs http://doc.rust-lang.org/rust.html#appendix:-rationales-and-... Is there any place to read about the Rust design?
      • dbaupp 12y ago
        http://doc.rust-lang.org/master/complement-design-faq.html http://doc.rust-lang.org/master/complement-design-faq.html
  • mkishi 12y ago
    I've always enjoyed informal guides, but oddly enough I share your frustration. Heck, I loved "Learn You a Haskell," yet this one reads very patronizing for some reason, and I can't figure out why.
    • maxerickson 12y ago
      I usually get that visceral reaction from pronoun heavy instructional material. I haven't decided if it is just a personal hang up or not. It's usually possible to omit pronouns and end up shorter, maybe at the cost of ending up a little dryer: "Welcome to the Rust guide. This is the place to learn how to program in Rust. Rust is a systems programming language with a focus on "high-level, bare-metal programming": low level control, but with zero-cost, higher level abstractions. We really think Rust is something special, and we hope you do too. The guide starts with a traditional "Hello, World!" program. Next a quick detour to introduce "Cargo", a tool for managing and building Rust programs and libraries. Then it's back to the language." If the guide actually builds something, the last sentence there could say "Then it's back to the language, starting with the basics and working up to <thing that is built>."
  • ZeroGravitas 12y ago
    This seems to be fundamental problem with programming texts. I was reading a couple of javascript books recently (eloquent javascript and javascript allonge) and I was struck by the sheer amount of background knowledge you needed to have. Most of that I've picked up over the last 20 years, but not all of it (or else I wouldn't be reading the books) so I constantly felt like I was having something I knew explained to me in too much detail or having crazy new concepts thrown at me without enough context. I mostly felt sorry for total newcomers, particularly as I realised most of my knowledge was historical trivia or workarounds rather than actual useful. Once I noticed the above, the amount of crufty irrelevances we have to deal with became obvious, and that's doubly true in JS for the browser. My only constructive thought was to break things into smaller skippable sections. I personally would skim rather than skip, but advanced warning that the section would only cover stuff I thought I already knew would be helpful.
    • k__ 12y ago
      I see this problem too, when teaching people. I tell them stuff and leave out the things that seem obvious to me. They can tell me, what is the missing bit.
    • scott_s 12y ago
      Mark Pilgrim solved this problem quite well in "Dive Into Python". He presented the working code first, at the beginning of each chapter ("diving in"). If you could read and fully understand the code, then you had no need to read the rest of the chapter. If there were only small things you didn't understand, you could skim to those sections. This philosophy is stated pretty clearly in the beginning of the book: You know how other books go on and on about programming fundamentals and finally work up to building a complete, working program? Let's skip all that. 2.1. Diving in Here is a complete, working Python program. It probably makes absolutely no sense to you. Don't worry about that, because you're going to dissect it line by line. But read through it first and see what, if anything, you can make of it. See: http://www.diveintopython.net/getting_to_know_python/index.html http://www.diveintopython.net/getting_to_know_python/index.h...
  • dmunoz 12y ago
    Hopefully some of the issues you're noticing will get fleshed out before the guide is officially linked from the rust homepage. I do agree with you though. I felt the same way about the guide from the first time I read (parts of) it, and I know we're not alone. I've commented before about how it's impossible to nail down the target audience, but it seems overly informal as a replacement to the current tutorials, especially compared to the "additional guides" that were linked to at the conclusion of the tutorial which really got down to business quickly. I've long been hoping that something like rustbyexample.com gets officially sanctioned and linked to from the homepage alongside the guide. As a small metric, the current tutorial is 942 to Hello World, the new guide is 1595 words, and rustbyexample.com is 239 words.
  • vertex-four 12y ago
    Most languages' official "guides" use a more-or-less informal tone, from my experience. I've not read through the Rust Guide yet, but I'd think this is a good thing, especially as most newcomers to Rust will be learning new concepts (its type system is very different from most languages, unless you're coming from the strongly typed functional world).
  • georgemcbay 12y ago
    I disagree. I like it a lot, particularly if "graded" as a first public draft. I'll admit right up front that there is a lot of subjective bias here, different people learn in different ways and you will never please everyone. So I'm not saying you are wrong, just that the guide appeals to me. In terms of the A/B split on target audience: A - Newbs) I'd argue that teaching people to code is way, way beyond the scope of any document like this, so the most logical starting target is someone who codes already but maybe doesn't have a ton of experience and maybe it is in a language very different from the one the guide is presenting. I think this guide hits that target pretty well as a straight-forward read. There are nitpicky things that maybe could be better, but luckily online guides like this can be expanded and iterated on. Obviously a newb isn't going to understand something like what a "closure" is inherently, but they have the whole rest of the internet to tell them that when they see the term in this guide and then google it to fill in the blanks. B - Non-Newbs) As an experienced programmer I think the guide is actually pretty great if you use the nicely presented ToC/index at the front as the primary interface to it. Click a concept and boom, you're looking at some nicely formatted example code along with some text that you can probably just skip over completely or skim because you already know what a closure is (for example) and just want to see the syntax for Rust. I remain a diehard Go partisan for now, but I think this guide is actually superior in a lot of ways to the combination of the "Go Tour" and "Effective Go" which, cute mascot aside, are a bit too much on the dry/clinical side for me as introductory material to a language.
  • coldtea 12y ago
    Programmer of 15+ years here, I disagree. It's a new language with some interestinf semantics than can be tricky even for those familiar with say C or Java or Python etc, so it's good that it's conversational -- it helps cater to both the new programmer and the experienced one in other languages. The skipping of cruft part I can do by myself, using "vgrep". This "skipping of cruft" because we're talking to "experienced programmers" is what makes Manfiles nearly useless, EVEN for experienced programmers, unless as a very basic flag reference.
    • the_af 12y ago
      Agreed. Manfiles are an excellent example! My usual investigation of an unfamiliar command goes like this: 1- Read the manfile. 2- If I was just trying to figure out the meaning of a flag, I'm done. 3- If it was anything else, I space out trying to understand the no-nonsense, terse, written-for-programmers style of the manfile. I usually fail. 4- Google.
      • bshimmin 12y ago
        Some manpages have quite helpful "examples" sections, eg. find(1). Usually, if they do, these sections are towards the end, which isn't necessarily the first place you'd look unless you knew that that was typically where they were. Many manpages, of course, do not provide examples.
      • iopq 12y ago
        I skip the manfile part and go straight to google. It's just as fast and I probably get better examples/explanation.
  • makmanalp 12y ago
    I think the problem is that references and tutorials fill different niches. This is a tutorial, basically. Tutorials are conversational, intuitive, hand-holding walkthroughs. If you think you already know enough, you should be able to just skim the reference. References are to the point, don't hand-hold, and get the job done.
  • jfarmer 12y ago
    Disclaimer: I've been writing programming curriculum professionally for the last three years. I do agree that it falls into the pit you describe, but I disagree that it's the style that's doing it. I think the style is fine, although there are always people it could turn off (e.g., you, perhaps). Here's an example of him falling into that pit, though: > By the way, in these examples, i indicates that the number is an integer. Ok, that's an important detail! You have to be reading _very_ closely to read that line. An expert will be skimming (as you say) and someone less less expert might not even realize how important that fact is. If I had to list "Five Rust Facts About Integers and Variable Bindings," noting that you signal an integer literal with that "i" character would definitely be on that list! As it's written, it's emphasized no more or less than any other part of the text.
    • roywiggins 12y ago
      Indeed. I skimmed and thought "Wait, we're using imaginary numbers now? What?" and then realized it just meant "this is an integer."
    • bjz_ 12y ago
      This is good criticism. If you have time, might you consider creating an issue? https://github.com/rust-lang/rust/issues https://github.com/rust-lang/rust/issues Steve reads all of the ones regarding documentation, and most likely would find it valuable.
      • jfarmer 12y ago
        Thanks! That's just the first instance I spotted — there were a few dozen similar things I saw after skimming for 2-3 minutes. I'll post an issue if I find time.
  • andrewflnr 12y ago
    Even within the domain of informal writing, there's a lot of fat in this piece that should be trimmed. I think that's what's triggering your distaste. However, once that is removed, as I'm sure it will, the tone will improve dramatically, and I suspect you'll only find it slightly annoying. My guess is that by far the most likely reader of this document is a noob to Rust with some degree of experience in other languages. To be safe we'll only assume basic programming experience. As a more experienced programmer, I don't mind seeing a few explanations of things I already know. From that perspective, this guide is a good compromise, once the technical issues are solved.
• someone13 12y ago
  Also note that the installation section is a bit out of date: they have Windows x64 binary installers now: http://www.rust-lang.org/install.html http://www.rust-lang.org/install.html
• antocv 12y ago
  Please Rust-lang, why, oh why, do you choose to name function 'fn' and module 'mod', dont you expect to read any of the programs you write!? How is anyone supposed to read fn main(). Fun main? Fen main? F of N? Is it related to ln in println? Ive tried rust, but it just doesnt parse well in my mind. More time is spent for me parseing out the bullshit terse keywords than the meaning of the program. Ada gets this right, there you have to write exactly what you mean, end begin, if then. Simple clear. Terseness, shorts and abbrevations, thts now hw you wrt anyng.
  • Vanzetti 12y ago
    You are not supposed to read programs aloud. What do you think it is, poetry? 'fn' is a symbol.
    • antocv 12y ago
      Well yeah, it should be poetry. Instead of, what, cryptic symbols to decipher? You dont read symbols?
      • Vanzetti 12y ago
        I know that 'fn' defines a function. It could be 'def', 'funct' or 'Ξ', it doesn't really matter. Also, what's the problem with pronouncing 'fn' as 'ef-en'?
        • bsdshepherd 12y ago
          > It could be ... Ξ Thank you. Somewhere, a transliteration vim plugin is struggling to escape. Based on user preferences it will display: def Σ(): print("LOL WUT?") Σ() -or- define sum(): print("LOL WUT?") sum() -or- Ξ Σ ⍋("LOL WUT?") Σ -or even- IDENTIFICATION DIVISION. PROGRAM-ID. Abomination. PROCEDURE DIVISION. DisplaySummary. DISPLAY "LOL WUT". STOP RUN.
          • antocv 12y ago
• gosub 12y ago
  let x = 5i; so, integers are written like complex numbers?
  • thristian 12y ago
    In this case, "i" is a type suffix meaning "int". 5u would be an unsigned int; 5i32 would be a 32-bit int; 5f64 would be a double precision float, and so forth.
    • gosub 12y ago
      I understood that, but it's an unfortunate suffix.
      • pestaa 12y ago
        I agree. Isn't it the default though? Could be implied when you choose to leave it out.
        • hornetblack 12y ago
          Yes it could be implied if left out. Due to type inference. `5` would be signed or unsigned if left off. Depends on how you use it. So you could try. use std::num::abs; let v = vec!['a', 'b', 'c', 'd']; let x = 3; let c = v[x]; // v.index (operator overload) constrains x to type uint. let y = abs(x); // error: failed to find an implementation of trait core::num::Signed for uint. // abs can't constain the type to an int because abs can take anything that // implements `Signed` (eg BigInt) If you wanted to make sure that x was signed. let v = vec!['a', 'b', 'c', 'd']; let x = 3i; let y = abs(x); // Ok as x is signed. let c = v[x]; // error: mismatched types: expected `uint` but found `int` If you really wanted to index to try an index with an int you can use a checked cast. let casted = x.to_uint(); // Returns None if x is negative or Some(x) if it's postive. Also a generic int doesn't have to be int or uint, it can be any integer value: signed: i8, i16, i32, i64 or int. Unsigned: u8, u16, u32, u64 or uint.
  • 12y ago
• SideburnsOfDoom 12y ago
  One stylistic nitpick / question. It says: > "We expected an integer, but we got (). () is pronounced 'unit', and is a special type in Rust's type system. () is different than null in other languages, because () is distinct from other types" Would it not be more accurate and more informative to compare the "special type" unit to "void" than to compare it to "null" ? The keyword "void" is a placeholder that says "nothing here" where normally there would be a type. It function more or less like a type. i.e. "public void foo { ... };" instead of "public int foo() { ... };" I understand "unit" as a "first class void". "null" on the other hand is a value, that can be placed in variables of many types.
  • the_mitsuhiko 12y ago
    The problem with void is that it's not a real type in C.
    • SideburnsOfDoom 12y ago
      Yes, totally. The same in java and c# too. That's why I said void is "more or less like a type" and asked about "unit" as a "first class void" - i.e. a "void" that is a real type that works like other types.
      • mercurial 12y ago
        Well, in Java you have http://docs.oracle.com/javase/7/docs/api/java/lang/Void.html http://docs.oracle.com/javase/7/docs/api/java/lang/Void.html Not exactly first-class but useful at times.
    • jeremyjh 12y ago
      Null is not a type either, and you cannot reference it in a definition. I think void is a closer match.
      • AaronFriel 12y ago
        As someone else describes, void is the "uninhabited" type, i.e.: it cannot be created. Void is a way of indicating the absence of valid output. I think null is wrong too, because it references the fact that in most languages, types are a sum type of "all possible valid inputs" plus "null". Rust avoids null and has no null pointers unless you use unsafe code. Unit means "there is precisely one instance of this type". It is the unitary type.
• eik3_de 12y ago
  leaving aside the first-mover advantages like community, docs, stdlibs, api stability, where do you see rust's advantages over go?
  • antocv 12y ago
    Security.
  • fleetfox 12y ago
    Control, lack of garbage collector.
    • ldng 12y ago
      Control, yes. Lack of garbage collector ? There is a garbage collector in the standard library : http://doc.rust-lang.org/std/gc/ http://doc.rust-lang.org/std/gc/ It gives you even more control I would say as you can choose when/if to use a garbage collector. Which is not always a bad idea (See https://news.ycombinator.com/item?id=8263811 https://news.ycombinator.com/item?id=8263811)
      • fleetfox 12y ago
        That was exactly what i meant :) I guess i ommited "forced".
      • steveklabnik 12y ago
        Gc<T> is not actually a garbage collector. It's a refcount + cycle detection. It was intended to turn into a real GC, but instead, it's in the process of being removed entirely. I've gone through and cleaned up all the references to it in our docs and marketing, so we stop misleading people with this notion.
        • mkishi 12y ago
          I'm curious about the reasoning behind the removal and what it means to Rust. Do you have any links on that? I tried looking on both Github and Discourse but couldn't find any more info.
• the_mitsuhiko 12y ago
  I like the informal style, I would not want to change it. Tutorials and introductions are supposed to be readable to complete beginners or developers that only used a simple programming language before. There are lots of small things I would want to change about the guide, especially in regards to which sections should be more in depth and which ones should be skipped for another guide, but that's why it's a first iteration.
• ch 12y ago
  It would be useful if the guide folded the Unix/Windows examples up into a single view (something like what the Spark docs do: https://spark.apache.org/docs/latest/quick-start.html#Basics https://spark.apache.org/docs/latest/quick-start.html#Basics) And then, perhaps, used some platform detection to display the more appropriate form by default. That way less space is used up by the parallel examples.
• phloxicon 12y ago
  I think it reads well but I would prefer if the examples given were correct first time around and then talk about what might go wrong, whereas right now, it describes what might go wrong and then how to do it correctly. For example, in the testing section, the first example code generates an error because it's scope is private. The section then shows how to fix this. I would prefer he showed the correct way first and then how to fix common errors. Also, I didn't see file IO but i probably overlooked that. Other than that, it's excellent. Very thorough and reads like a book.
• octo_t 12y ago
  +1 from me for the `curl | sudo sh` disclaimer. Even if the only thing it does is stop people complaining about it :)
  • JoelMcCracken 12y ago
    I always like seeing and doing curl foo.sh / sudo bash foo.sh
  • mindslight 12y ago
    Even if there were five cute disclaimers, suggesting that command would still be irresponsible. The problem is that it hurts the people who are the least knowledgeable. Anyone with a modicum of experience downloads the script first, finds out it's 475 lines, and then chooses a different method that is at least tracked by git. At least get rid of the wholly-unnecessary sudo. At that point, it would at least be comparable to tar xvzf rust.tgz && ./rustc (still less auditable though).
• steveklabnik 12y ago
  Hi everyone! I just woke up to find all this, and I'm speaking at a conference today where there's no laptops allowed, so we'll see when I get to read these comments. A few things: 1. Consider this a 'first draft.' I wrote this in sections, see [1], and now it's time to edit as a whole. 2. Because of that, there are still changes coming. There's even an active one in the queue right now. [2] 3. This guide is fairly long (The PDF is 80~ pages), tries to make little assumptions about systems programming knowledge, and will get you from 'I know nothing about Rust' to 'I'm an intermediate Rust programmer.' There's plans to make an abridged version for people who are already familiar with systems or want something faster with less explanation. To expand on (3) a bit, one of the hard parts of teaching is that you have such varying background levels of skill in your audience. This means different people need different things, one learning resource will never fit all. I very specifically went for extra explanation and an informal tone with this piece, based on my years of experience teaching programmers new languages. You all here are generally much further along, know more programming concepts and features, and are just generally more advanced. I want to include _everyone_ with the introductory documentation I write, and that means spelling things out a bit more. And it also means you all may not like it. You'll probably prefer the abridged version. Feedback very welcome. I'll read all this eventually, or just open some issues. 1: https://github.com/rust-lang/rust/pulls?q=is%3Apr+author%3Asteveklabnik+is%3Aclosed https://github.com/rust-lang/rust/pulls?q=is%3Apr+author%3As... 2: https://github.com/rust-lang/rust/pull/17155 https://github.com/rust-lang/rust/pull/17155
  • izietto 12y ago
    What is your opinion about this HN comment [0] (TL;DR the guide should be terse to a skilled profile, overly explanatory to a beginner)? I personally agree with him [0] https://news.ycombinator.com/item?id=8306868 https://news.ycombinator.com/item?id=8306868
    • steveklabnik 12y ago
      Fundamentally disagree. Terse is bad for teaching. There's value in having something terse for those who know they want it, but it's bad for primary material.
• bmurphy1976 12y ago
  Wow. That's a lot of text. I'm going to side with others out there, it's too informal and needs to be tightened up considerably. It's a decent start, but needs some serious editing. Good luck!
• gtani 12y ago
  quick comments (from s.b. who has been recently learning D and cuda C++) - Most important, and nota bene: I liked it! - this seems to be targeted as a crossover guide for experienced c/java/C++/C# family devs, but written a little below that level (whereas tutorial would be for people that have some programming experience in any language - top level summaries before you launch into litany of language features: what is the object model, are there entities that can be inherited, how do interfaces/traits/mixins? how does allocation/initialization/destruction/cleanup typically work? - Needs to note conventions ("_" in file/directory names, 4 space soft tabs) vs things enforced by compiler/tooling - needs inline references/footnotes/bibliography for H-M type inference, FP style pattern matching, i.e. the "new" FP concepts for people without haskell/ocaml/scala experience
• niix 12y ago
  This language really interests me, but I would like to know some real world applications that are being used for it. While I may enjoy writing it as a hobby, could this be something that I utilized in production as well?
  • reubenmorais 12y ago
    Mozilla is writing Servo, a parallel browser engine: https://github.com/servo/servo https://github.com/servo/servo There's a group of game developers writing Piston: http://www.piston.rs/ http://www.piston.rs/
  • pdovy 12y ago
    The last I heard OpenDNS was using it for some data processing and Skylight was using it - see "Is Rust Ready Yet?" in http://cmr.github.io/blog/2014/01/12/the-state-of-rust-0-dot-9/ http://cmr.github.io/blog/2014/01/12/the-state-of-rust-0-dot.... This is 9 months old now, so maybe there are more projects now. That said I think the language is still too much in flux to really use for production systems. It seems to still be undergoing syntax changes, standard library changes, etc that might make code that works today not compile tomorrow.
    • davidu 12y ago
      We're using it. (OpenDNS)
  • bjz_ 12y ago
    Game development, Application development (things like photoshop), high-load web service backends, embedded systems... basically anywhere that C++ is currently used. The cool thing about Rust is that it guides you towards writing performant code, with a much lower likelihood of ugly bugs. This means it has a lower barrier to entry that languages like C++ or C, where you need a high level of domain specific knowledge and experience in to avoid nasty pitfalls and mistakes.
  • damien 12y ago
    Probably the largest application written in Rust is the Rust compiler itself.
• Bob8000 12y ago
  As a n00b programmer, this entry in this guide was the first entry that made the concept of closures clear to me. I don't know if it's because of the use of the two pipes to denote a closure, but it makes it clear for some reason: let x = 3; fn fun () -> () { println!("{}", x) } // cannot capture from enclosing scope let closure = || -> () { println!("{}", x) }; // can capture from enclosing scope fn fun_arg (arg: int) -> () { println!("{}", arg + x) } // cannot capture let closure_arg = |arg: int| -> () { println!("{}", arg + x) }; // can capture
• deleted 12y ago
  [deleted]