math/rand: Example should demonstrate (in comments) how to do proper seeding

[kevinburke]

The example for math/rand reads:

rand.Seed(42) // Try changing this number!
answers := []string{
    "It is certain",
    "It is decidedly so",
    // ...
}
fmt.Println("Magic 8-Ball says:", answers[rand.Intn(len(answers))])

"Try changing this number" isn't super helpful advice (change to what?) and I have to look up what to plug in every time. For example last time I needed a math/rand, I copied from the other example, but I created my own *rand.Source when I didn't need to, because that's what the other example does.

I have been using Go for 5 years now and if I have to look up how to do it, odds are that other people do too.

It would be good if we could provide a better value in the comment, for example:

// "rand.Seed(42)" produces predictable outputs each time. To produce random 
// outputs on each run, replace with rand.Seed(time.Now().UnixNano())
rand.Seed(42) 
answers := []string{
    "It is certain",
    "It is decidedly so",
    // ...
}
fmt.Println("Magic 8-Ball says:", answers[rand.Intn(len(answers))])

[agnivade]

/cc @robpike - thoughts ?

[robpike]

It's not clear to me how much of the computing basics the documentation for Go must provide. To me, the need to explain seeding seems below the bar. I do admit though that "chang[e] this number" is poor. What I'm not sure of is what the right seed should be. I believe UnixNano can be very poor on some systems, but using crypto/rand to seed is overkill. Rather than just giving a recipe, perhaps explain:

Seeding with a constant results in the same random sequence each run. For different numbers, seed with an unpredictable value, such as time.Now().UnixNano(), which yields a large constantly-changing number. Or use crypto/rand to seed for even less predictability.

[gopherbot]

Change https://golang.org/cl/112775 mentions this issue: math/rand: clarify documentation for Seed example