Guide: Variable bindings

[steveklabnik]

Whew. So much here! Feedback very welcome.

This is the first part where we actually start learning things. I'd like to think I struck a good balance of explaining enough details, without getting too bogged down, and without being confusing... but of course I'd think that. 😉

As I mention in the commit comment, We probably want to move the guessing game to the rust-lang org, rather than just having it on my GitHub. Or, I could put the code inline. I think it'd be neat to have it as a project, so people can pull it down with Cargo. Until we make that decision, I'll just leave this here.

[thehydroimpulse]

While the code is shown after this sentence, it seems a bit confusing at first. One probably doesn't get what "projects directory" means until they see the code. Perhaps something like "Go to where you keep your projects in"?

[steveklabnik]

In the very beginning of the tutorial, we created a projects directory, and talked about it explicitly. It was created at this location.

[thehydroimpulse]

Gotcha. That makes more sense.

[mdinger]

I'm a rust novice and my perspective on let x; failing was slight puzzlement. I was pretty sure I'd seen it compile before. When I tested it, I suspected Rust must have been updated.

It wasn't until I saw huonw's example below that I realized what I had missed:

let x;
x = 2;

[mdinger]

You don't necessarily have to print out the error messages verbatim. People aren't likely to read them entirely anyway.

fn main() {
    let x: int; // Warning: unused variable
}

The above is perhaps better than the entire warning anyway. Warnings could also change subtly between versions (I have no idea how likely though).

If the playpen is embedded like in Rust by Example, error messages aren't needed because compiling will provide them. This really helps keep examples compact. It would also allow you to suggest changes like Japaric:

fn main() {
    return;
    // ^ Try commenting out this line
    println!("Hello world!");
}

Also, you don't have to break up code by text (just pointing it out; what you do is up to you). Japaric gets a lot of mileage out of inline commenting in RustbyExample. The essentials of your example is below yet it takes 10 times the space:

fn main() {
    // Compiles:
    // Read as: `x` is a binding with the type `int` and the value `five`
    let x: int = 5;

    // Compiles
    let y: int;
    println!("Hello world!");

    // Error
    let z: int;
    println!("The value of y is: {}", z);
}

Keeping them together makes lines easier to compare. It also gives you opportunity for more contrasting examples.

[steveklabnik]

@mdinger thanks for the suggestions. I do want to link to the sandbox eventually, but first, I'd prefer to just write everything inline.

Eventually all of the examples, everywhere, should go to the sandbox.

[steveklabnik]

If @huonw likes my updates, I think this is ready for a r?

[huonw]

(I like the updates.)

[steveklabnik]

Cool. @brson, r?

[pnkfelix]

1. You should use the term "String interpolation", not just "Interpolation", to distinguish this from e.g. linear interpolation.
   • The latter is what I get when I google for "interpolation" today; I had to add "string" to get usable links.
   • So, use of the full term will make it easier for the reader to get the right result when searching for more information.
   • (It would probably be a good exercise to go through and make sure every similar vocab word that is introduced or pseudo-defined in the guide currently gets a plausible result from google.)
2. In particular, in this case I would say `"String interpolation is a programming term that means ..."
   • Further explanation for the latter suggestion: I read the use of "fancy" here as carrying an "aww shucks" tone, which I dislike, as it brings with it underlying theme of "don't worry your little head about big words like "Interpolation." I see the latter as dismissive of the reader, rather than respectful. But I suspect that others may think that an "aww shucks" tone it makes the text more approachable, so I will not push hard for this latter change.

[steveklabnik]

I see the latter as dismissive of the reader, rather than respectful. But I suspect that others may think that an "aww shucks" tone it makes the text more approachable,

This is a constant issue, which I'm not sure how to resolve. I had a really interesting, lengthy discussion with someone about "basically," the other day: I read it as synonymous with 'essentially,' and others read it as super condescending.

Gimme a quick moment and I'll fix both of these. I do think that searching on google for terms is a good idea, but I'd rather do that as part of a final editing pass than as I go, that's the kind of work that's nice to just do all at once.

[pnkfelix]

@steveklabnik okay, if you address the nit I noted, I think the whole thing will be ready to be squashed and then r-plussed

[steveklabnik]

This is ready.

[steveklabnik]

This is re-r+ ready. I just dropped the graves, which rustdoc had issue with.