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

math/rand: unclear documentation on Int31n & associated method familly #26765

Closed
ladydascalie opened this issue Aug 2, 2018 · 10 comments
Closed

math/rand: unclear documentation on Int31n & associated method familly #26765

ladydascalie opened this issue Aug 2, 2018 · 10 comments

Comments

@ladydascalie
Copy link
Contributor

@ladydascalie ladydascalie commented Aug 2, 2018

Please answer these questions before submitting your issue. Thanks!

What version of Go are you using (go version)?

go version go1.10.3 darwin/amd64

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

Not relevant, documentation related

What did you do?

I read the following piece of documentation:

Int31n returns, as an int32, a non-negative pseudo-random number in [0,n). It panics if n <= 0.

What did you expect to see?

I expected to understand the meaning of n in that context.

What did you see instead?

I didn't.

@ladydascalie
Copy link
Contributor Author

@ladydascalie ladydascalie commented Aug 2, 2018

I intend to fix this.

@gopherbot
Copy link

@gopherbot gopherbot commented Aug 2, 2018

Change https://golang.org/cl/127549 mentions this issue: math/rand: tweak documentation

@as
Copy link
Contributor

@as as commented Aug 2, 2018

I expected to understand the meaning of n in that context.

That's self-evident if you include the signature of the function being documented.

func Int31n(n int32) int32
    Int31n returns, as an int32, a non-negative pseudo-random number in [0,n)
    from the default Source. It panics if n <= 0.

Which tool did you use to get an output without the function signature (above is the standard go doc rand.Int31n)?

@robpike
Copy link
Contributor

@robpike robpike commented Aug 3, 2018

It's very common mathematical notation that I've seen since junior high school. Does the Go documentation need to describe things like this? It's really a policy question: What are we allowed to assume? One person being confused by a reference or a notation is indeed unfortunate, but we cannot be expected to explain everything to everyone, nor should we.

Where do we draw the line?

@ianlancetaylor
Copy link
Contributor

@ianlancetaylor ianlancetaylor commented Aug 3, 2018

One possible guideline for cases where people report being confused is to make sure that a web search will provide the answer. Unfortunately searching for "[0,n)" provides nothing. But if we like this principle we could, for example, write "a non-negative pseudo-random number in (using interval notation) [0,n)".

@jimmyfrasche
Copy link
Member

@jimmyfrasche jimmyfrasche commented Aug 3, 2018

Current issue aside, why do the docs both say "non-negative" explicitly and include the explicitly non-negative interval?

@robpike
Copy link
Contributor

@robpike robpike commented Aug 3, 2018

I like the idea of "(using interval notation)" and the general policy of easy search. I agree it's hard to find "[0,n)" by a web search, but the rewording fixes that an sets a nice precedent.

@mikioh
Copy link
Contributor

@mikioh mikioh commented Aug 3, 2018

I personally think it's fine to use symbols/notations defined in ISO/IEC 80000 family. If the confusion comes from various representation schemes of the symbols, I mean, language-defined math. operators/notations vs. ISO/IEC 80000 math. operators/notations, we can use math. operators in Unicode for clarification:

[0,n) and n <= 0
[𝟢,𝑛) and 𝑛 ≤ 𝟢
@ladydascalie
Copy link
Contributor Author

@ladydascalie ladydascalie commented Aug 3, 2018

It's very common mathematical notation that I've seen since junior high school.

@robpike Unfortunately, I am a high school drop-out. I have not been taught this notation, and it was very difficult to search and find the right information, without pre-existing knowledge.

Of course, this is entirely due to my lack of knowledge, I fully admit that, but I am willing to bet that I may not be the only person in this situation.

the rewording @ianlancetaylor proposes is very much satisfactory in my opinion, it would have given me enough information to find the answer to my question. I shall update my CL to reflect that.

@RalphCorderoy
Copy link

@RalphCorderoy RalphCorderoy commented Aug 3, 2018

I too can remember not knowing this notation, way before Go. I asked a few programmer friends and found out it was 'interval notation'. I just did a few Google searches. Nothing found for phrases "interval notation" or "half open" with site:golang.org or site:docs.python.org. So Python doesn't seem to explain it either, as a data point.

https://books.google.com/ngrams/graph?content=interval+notation%2Chalf+open&year_start=1960&year_end=2010&corpus=15&smoothing=3&share=&direct_url=t1%3B%2Cinterval%20notation%3B%2Cc0%3B.t1%3B%2Chalf%20open%3B%2Cc0 shows both phrases trending up in recent decades. That matches my gut feel that they're seen more often and thus more likely to be understood.

@ianlancetaylor ianlancetaylor added this to the Unplanned milestone Aug 3, 2018
@gopherbot gopherbot closed this in 669ac12 Aug 3, 2018
@golang golang locked and limited conversation to collaborators Aug 3, 2019
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
8 participants
You can’t perform that action at this time.