Basics: improve random number examples #255

dhardy · Jul 22, 2017

I noticed the random examples were quite short and didn't document range for floating point cases. Improved.

Caveat: this doesn't explain why the .ind_sample method is used. I don't understand myself why the Sample trait (taking mutable reference to the range) exists, and if it does have a use-case it should probably have been named MutSample. But I digress.

budziq · Jul 24, 2017

budziq requested changes Jul 24, 2017

View changes

Hi @dhardy,, thanks for taking interest!

Some of our examples (as well as the actual rand crate) certainly need more polish. We'd love to have you on board! 👍

Here are some suggestions below (sorry for the terse form but I'm currently on holidays mobile only)

budziq · Jul 24, 2017

src/basics.md

 }
 ```

+Alternatively, one can use the [`Range`](https://doc.rust-lang.org/rand/rand/distributions/range/struct.Range.html) distribution.


I would not introduce this section at all (and all below) as we have Ranges covered in:

Generate random numbers within a range

Generate random numbers with normal distribution

but you are welcome to improve these examples (description and/or code)

Disagree. If someone wants to generate numbers within a range, they'll follow that link, and it's fair to show them the two ways of doing it there. If they don't understand the second example, no real problem since they already have an alternative.

On the other hand, understanding how to do that given just the normal distribution example may not be so obvious.

you are essentially duplicating an existing example. this essentially ads only noise.
If the other examples are not fitting to this one or not providing a clean progression /learning curve for the reader you are welcome to suggest (even fundamental) changes.

We are trying to provide examples that are as self-contained and bitesized as possible while solving a specific problem

on the other hand "simulating a six sided die roll" might be a problem that merits its own example so we might decide to either extract it as a separate one or rewrite one of the previously mentioned ones 👍

budziq · Jul 24, 2017

src/basics.md

@@ -4,7 +4,7 @@
 |--------|--------|------------|
 | [Read lines of strings from a file][ex-std-read-lines] | [![std-badge]][std] | [![cat-filesystem-badge]][cat-filesystem] |
 | [Read and write integers in little-endian byte order][ex-byteorder-le] | [![byteorder-badge]][byteorder] | [![cat-encoding-badge]][cat-encoding] |
-| [Generate random floating point numbers][ex-rand-float] | [![rand-badge]][rand] | [![cat-science-badge]][cat-science] |
+| [Generate random numbers for simple types][ex-rand-simple] | [![rand-badge]][rand] | [![cat-science-badge]][cat-science] |


"random numbers for simple types" sounds a little off I would suggest leaving only "random numbers"

I know what you are getting at but a new reader comming with zero experience might get confused.

Also if you are changing the example title and tag, please update these in intro.md too or the links will get broken.

budziq · Jul 24, 2017

src/basics.md

 }
 ```

+Example output:


I the example is pretty basic. I'm not sure there is anything particularly unexpected in the stdout. I would suggest removing the whole "example output" section as it ads noise.

What would be really useful is a run button below each example. Is this planned?

Is this planned?

Sorry I wanted to mention it as the main reason but it slipped my mind. Yep the run button is already implemented but disabled due to rust playpen historically not supporting crates. Currently we are coordinating list of supported crates with playpen guys https://github.com/brson/rust-cookbook/issues/87

budziq · Jul 24, 2017

src/basics.md

+<a name="ex-rand-simple"></a>
+## Generate random numbers for simple types
+
+The `rand` crate provides a convenient source of psuedo-random numbers.


Backticks are for code, we would normally use link syntax with square brackets in this context.
Also we tend to suggest for the description to actually mention what is going on with links to docs.rs for the key identifiers used in the code (rand::thread_rng and Rng::gen). This sentence is less useful by itself as rand is already referenced and readers already know that they looking for pseudo random generator. What they don't have are the links to docs.

Actually, they do have a link: the badge below links. Never mind, no real reason not to include another link.

I originally wanted to suggest removing the whole

"The rand crate provides a convenient source of psuedo-random numbers"

as all of that information is either already available (as you have noted) or obvious

budziq · Jul 24, 2017

src/basics.md

@@ -122,11 +124,30 @@ extern crate rand;
 use rand::Rng;

 fn main() {
+    // Each thread has an automatically-initialised random number generator:


generally such information would be conveyed in the textual description mentioning key code identifiers linked to crate docs instead of comments (we try to keep comments to absolute minimum striving to make descriptions and code as self explanatory as possible)

budziq · Jul 24, 2017

src/basics.md

+    
+    // Floating point numbers are uniformly distributed in the half-open range [0, 1)
+    println!("Random float: {}", rng.gen::<f64>());
+    println!("Random floats: {:?}", (0..5).map(|_| rng.gen()).collect::<Vec<f32>>());


Arguably this would belong to a separate example or one of the more advanced ones below.

budziq · Jul 24, 2017

src/basics.md

+    let n1: u32 = rng.gen();
+    let n2: u16 = rng.gen();
+    let n3: u8 = rng.gen();
+    println!("Random u32, u16, u8: {}, {}, {}", n1, n2, n3);


The output formatting here is a little off. I would suggest pairing output with types.

dhardy · Jul 24, 2017

@budziq updated, including changing the "normal distributions" section to be a "general distributions" section and reference the previous usage.

budziq · Jul 24, 2017

budziq requested changes Jul 24, 2017

View changes

few more suggestions and a commit squash into a single one

budziq · Jul 24, 2017

src/intro.md

 | [Generate random numbers within a range][ex-rand-range] | [![rand-badge]][rand] | [![cat-science-badge]][cat-science] |
-| [Generate random numbers with normal distribution][ex-rand-dist] | [![rand-badge]][rand] | [![cat-science-badge]][cat-science] |
+| [Generate random number distributions][ex-rand-dist] | [![rand-badge]][rand] | [![cat-science-badge]][cat-science] |


"Generate random number distributions" is slightly inaccurate. We are not generating distributions but rather random number with/of/described by given distribution. I would suggest to rewrite the title as:
"Generate random number with given distribution"

budziq · Jul 24, 2017

src/basics.md


-The `rand` crate provides a convenient source of psuedo-random numbers.
+The [`rand`] crate provides a convenient source of psuedo-random numbers.


please remove the backticks. it is a normal link and not linked code

budziq · Jul 24, 2017

src/basics.md

-Creates a [`Normal`] distribution with mean `3` and standard deviation `5`
-and generates a random value with [`IndependentSample::ind_sample`].
+You've already seen how to create numbers with uniform distribution [above][ex-rand-range]
+(using [`Range`]). Other distributions are used in the same way: create a distribution, then


most of this description is obvious from the trivial code below no need to be verbose here.

budziq · Jul 24, 2017

src/basics.md


 [![rand-badge]][rand] [![cat-science-badge]][cat-science]

-Creates a [`Normal`] distribution with mean `3` and standard deviation `5`
-and generates a random value with [`IndependentSample::ind_sample`].
+You've already seen how to create numbers with uniform distribution [above][ex-rand-range]


we don't aim to make the cookbook into a tutorial (what I've meant by "progression" was if there is any missing information between examples or if these are not sorted by their difficulty). We strive for problem solution (hence cookbook) approach of self-contained examples.

I would roll back the original description here as it was short and to the point and just link to alternative distributions.

budziq · Jul 24, 2017

src/basics.md

    let mut rng = rand::thread_rng();
+    
+    // mean 2, standard deviation 3:
+    let normal = Normal::new(2.0, 3.0);


any reason to change the order of statements or distribution parameters?

budziq · Jul 24, 2017

src/basics.md

@@ -566,8 +563,11 @@ fn main() {
 [`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
 [`Normal`]: https://doc.rust-lang.org/rand/rand/distributions/normal/struct.Normal.html
 [`IndependentSample::ind_sample`]: https://doc.rust-lang.org/rand/rand/distributions/trait.IndependentSample.html#tymethod.ind_sample
+[`rand`]: https://doc.rust-lang.org/rand


there is already a link to rand crate with proper form.

[normal link] `code` [`linked code`]

budziq · Jul 24, 2017

src/basics.md

@@ -168,7 +158,7 @@ fn main() {
 }
 ```

-Alternatively, one can use the [`Range`](https://doc.rust-lang.org/rand/rand/distributions/range/struct.Range.html) distribution.
+Alternatively, one can use the [`Range`] distribution (otherwise known as uniform).


👍 I would linkify the "uniform" into some autharitive resource

I would rename the thing if I could. I may actually try, but it's not high up the priorities of what that crate needs.

I meant making "uniform" into a link pointing to something like:

https://en.m.wikipedia.org/wiki/Uniform_distribution_(continuous)

budziq · Jul 24, 2017

src/basics.md

@@ -128,26 +128,16 @@ fn main() {
    let mut rng = rand::thread_rng();
    
    // Integers are uniformly distributed over the type's whole range:
-    let n1: u32 = rng.gen();


no reason to leave out the u32 it was actually neat.

budziq · Jul 24, 2017

src/basics.md

    let n2: u16 = rng.gen();
-    let n3: u8 = rng.gen();
-    println!("Random u32, u16, u8: {}, {}, {}", n1, n2, n3);
+    println!("Random u8: {}; random u16: {}", n1, n2);
    println!("Random i32: {}", rng.gen::<i32>());


I would suggest for the formatting to be uniform for all types. each on separate line

It's deliberately not uniform. It's supposed to show readers different ways of doing things, so they can use whichever they like.

here I meant output formatting I perfectly understand why you are obtaining the values in various ways.

Unless you mean to teach the users that they can print two variables on the same line without a newline in between.

dhardy · Jul 24, 2017

You know, if you can put this much effort into constructive criticism, I might as well let you write it yourself. There's only so much time I'm prepared to waste on a cookbook I'm sure most people won't give more than a quick glance anyway.

budziq · Jul 24, 2017

You know, if you can put this much effort into constructive criticism, I might as well let you write it yourself.

Well it certainly takes a lot of effort and motivation considering I am juggling +10PR's while on vacation with only mobile at my disposal.

Each an every one is held under the same scrutiny in order to have consistent format and quality. Please note that while the presentation and form might not look like it the cookbook is aimed to become an official resource once its out of its pre-alpha stage.

I agree that contribution is painful at the moment (I guess some kind of guideline for the examples would help)

There's only so much time I'm prepared to waste on a cookbook

Well I would not call it "wasting" you are helping a lot. For instance I would certainly fix the examples myself if I had even a slightest notion that there is a problem in them.

We are thinking about the final form and format for cookbook and if anything, your problems and suggestions will have an impact on the final output.

I guess that this PR might go smother If we had discussed your suggestions prior to you making the actual work. But unfortunately I did lack the means to drive the conversation.

Sorry to have discouraged you :(

brson · Jul 25, 2017

This looks great, @dhardy. Thanks. I rebased and merged it. I did change the language in the non-uniform distributions example to not reference previous examples. For the moment at least it is true that the examples are pretty independent, and it's pretty likely that the format of the book will change drastically before any kind of final release.

I do think it would be worth having a better narrative progression between examples so that it reads nicely as a book, leads the reader on a journey of some kind. This is great for now though - we're going to have to circle back for a big editing pass in the future.

Thanks for reviewing @budziq (but do feel free to take some time off while you are traveling).

Basics: improve random number examples

Loading status checks…

53d15ed

Basics: update random number distributions; tweaks to other prior ran…
…d sections

Loading status checks…

ccd43b4

brson closed this Jul 25, 2017

rust-lang-nursery/rust-cookbook

Join GitHub today

Basics: improve random number examples #255

Conversation

dhardy commented Jul 22, 2017

budziq requested changes Jul 24, 2017 View changes

budziq left a comment

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

budziq Jul 24, 2017 • edited

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

dhardy commented Jul 24, 2017

budziq requested changes Jul 24, 2017 View changes

budziq left a comment

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

dhardy commented Jul 24, 2017

This comment has been minimized.

budziq commented Jul 24, 2017 • edited

This comment has been minimized.

brson commented Jul 25, 2017

brson closed this Jul 25, 2017

budziq requested changes Jul 24, 2017

View changes

budziq Jul 24, 2017 •

edited

budziq requested changes Jul 24, 2017

View changes

budziq commented Jul 24, 2017 •

edited