
Rust Guide - bilalhusain
http://doc.rust-lang.org/guide.html
======
axaxs
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.

~~~
jfarmer
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.

~~~
bjz_
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
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.

------
steveklabnik
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%3As...](https://github.com/rust-
lang/rust/pulls?q=is%3Apr+author%3Asteveklabnik+is%3Aclosed)

2: [https://github.com/rust-lang/rust/pull/17155](https://github.com/rust-
lang/rust/pull/17155)

~~~
jblow
Hey Steve,

Who do we have to harangue to get Rust to rename "Vector"? It is kind of
embarrassing and confusing terminology, and there is no reason to propagate
it. Just call an array an array and an immutable array an immutable array.

There's no good reason to perpetuate the mistakes of the C++ people.

(Note to those not understanding the objection: A vector is defined an element
of a group that is closed under addition and multiplication. This is a very
specific and very widely-useful meaning, and any program that does stuff with
math is going to use vectors. So when you come along and put into your
standard the idea that 'vector' means an arbitrary collection of elements that
probably are not even scalars, you not only show that you don't know what
vector means, but you confuse the programs of many many of your users, because
now they have two totally different things both of which are called Vector and
that are both used very heavily. [There is no way in hell anyone is going to
call a math vector anything but vector, since that would be insanely
confusing.])

~~~
steveklabnik
Short because I'm on my phone: my sibling is correct. But I think it's
important to understand that Vec<T>, [T, ..N], and &[T] (vectors, arrays, and
array slices) aren't different because of mutability. The differences are in
ownership, growability, and where the backing memory is allocated. Also,
Vec<T> isn't part of the language, but part of the standard library, while the
other two are language items. Any RFC would have to take this into account.

~~~
ecl3ctic
I know you're not exactly opposing the above comment, but I'll make a
supporting argument here which acknowledges what you've said:

I feel as though we can retain understanding of those differences without
using the name "Vec", which can be considered a poor choice for the reasons
mentioned above (by C++ and Rust alike).

Array<T> for a growable array

[T, ..N] for a fixed-length array

&[T] for a slice into either of these array types

Even forgetting the mathematical concept, I would argue that throwing the term
"Vector" into the mix only makes things more complicated than they need to be,
since sticking to "Array" homogenizes everything. For good reason, we don't
call a resizable string a "Hobnob" in an attempt to disambiguate, so why call
a resizable array a "Vector", which makes just as much sense?

------
SideburnsOfDoom
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
The problem with void is that it's not a real type in C.

~~~
jeremyjh
Null is not a type either, and you cannot reference it in a definition. I
think void is a closer match.

~~~
stonemetal
First you have to say if you are talking about () the type or () the value. ()
the type is fairly close to void in meaning. () the value is fairly close to
null in meaning. Thus both comparisons are accurate, which is applicable
depends on which () you are referring to.

While your post is correct for () the type, if I consider () the value, your
post could be transformed without loss of accuracy to:

Void is not a value either, and you cannot return it from a function. I think
null is a closer match.

Value or type neither half is the whole story.

~~~
bjz_
I guess you could argue that 'null' refers to the '1' in a sum type 'T + 1'. I
still think 'unit' is the most precise term though, especially seeing as Rust
doesn't have structural sum types. `None` is the closest we get to null.

------
phloxicon
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.

------
gtani
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

------
ch
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.

------
someone13
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)

------
the_mitsuhiko
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.

------
gosub

        let x = 5i;
    

so, integers are written like complex numbers?

~~~
sixbrx
On the other hand, not many languages use lowercase 'i' for complex number
literals, in fact I can't think of any right now.

~~~
cheepin
I can't even think of a language that has first class complex numbers, let
alone complex number literals.

~~~
kragniz
Python does.

    
    
        >>> 5 + 2j
        (5+2j)
        >>> 2j * 2j
        (-4+0j)

------
octo_t
+1 from me for the `curl | sudo sh` disclaimer. Even if the only thing it does
is stop people complaining about it :)

~~~
mindslight
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).

------
niix
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?

~~~
pdovy
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...](http://cmr.github.io/blog/2014/01/12/the-state-of-
rust-0-dot-9/). 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
We're using it. (OpenDNS)

------
bmurphy1976
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!

------
eik3_de
leaving aside the first-mover advantages like community, docs, stdlibs, api
stability, where do you see rust's advantages over go?

~~~
matthewmacleod
The languages (to me at least) seem to have little overlap. Maybe a better
question would be "Why are there so many comparisons between Rust and Go"?

~~~
Pxtl
They both billed themselves as "modern C" but Go failed to deliver on that so
instead it's now light/modern/ Java. Rust hopes to succeed as a "modern C"
where Go failed.

------
antocv
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.

~~~
easytiger
fn & mod are fine. no worse than cdr & car.

Variable declaration and type annotations in rust are the thing you should be
confused/angry/sad about.

~~~
saosebastiao
Yes! This is what drives me the most crazy about rust:

    
    
        fn foo<<W<>W>G<>GGW>>>F<<D>F>>A>(bar: AJK<<<DUoSJK><<>S>>>){
        ...
        }
    

Okay, I'm probably being a jackass, but I find Scala's use of [] for nested
type annotations to be much easier to parse.

~~~
lambda
I'm wondering if it would be more readable with actual angle brackets rather
than less than and greater than signs.

    
    
      from_str::<Option<uint>>
    

vs

    
    
      from_str::‹Opton‹uint››
    

Hmm. Those are a little lightweight, are actually angle quotes, not angle
brackets. Actual angle brackets aren't available on my keyboard, but would
look like:

    
    
      from_str::⟨Option⟨uint⟩⟩
    

Jeez, why does Unicode have so many different variations on angle brackets?
The above are "mathematical left/right angle bracket", but there's also:

    
    
      from_str::〈Option〈uint〉〉
    

Which uses "left/right-pointing angle bracket" and:

    
    
      from_str::〈Option〈uint〉〉
    

Which uses "left/right angle bracket"

At least in the font I'm typing this in, the "left/right-pointing angle
brackets" look the best to me. It would be really nice if now that Unicode is
ubiquitous, we could standardize on keyboard layouts that get you access to
more punctuation like this, so that people didn't have to keep fighting over a
fairly limited amount of punctuation to use as technical notation in
programming languages.

~~~
steveklabnik
There are some proposals to make that syntax go away. ::<> is certainly
something we're not happy about.

