Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Closed
kevinburke opened this issue May 10, 2018 · 3 comments
Closed

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

kevinburke opened this issue May 10, 2018 · 3 comments
Labels
Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.

Comments

@kevinburke
Copy link
Contributor

kevinburke commented May 10, 2018 •
edited

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))])
@kevinburke kevinburke added Documentation NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. labels May 10, 2018
@agnivade
Copy link
Contributor

/cc @robpike - thoughts ?

@robpike
Copy link
Contributor

robpike commented May 10, 2018

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.

@agnivade agnivade added NeedsFix The path to resolution is known, but the work has not been done. and removed NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. labels May 11, 2018
@gopherbot
Copy link

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

@golang golang locked and limited conversation to collaborators May 12, 2019
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Documentation FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@kevinburke @agnivade @robpike @gopherbot