Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:121312
MIME-Version: 1.0
Date: Sat, 14 Oct 2023 19:47:58 +0200
Message-ID: <CAL-Ucw7H4zcbnhUJHHPi9=KX9NtPEVKiCOyNz+TTJfdwkzLRTw@mail.gmail.com>
To: internals@lists.php.net
Content-Type: text/plain; charset="UTF-8"
Subject: Better name for method Randomizer::nextFloat()
From: david@grudl.com (David Grudl)

I would like to suggest changing the name or removing the nextFloat() method,
which is coming to PHP 8.3.

The Random\Randomizer class will have two new methods for generating
random numbers:
- getFloat($min, $max [, $boundary])
- nextFloat()

Now please try to guess what these methods do and, more importantly,
how they differ. I bet no one can guess. Which is, of course, a
symptom of poor naming. And as we know, naming along with cache
invalidation are the most complicated things :-)

What is the correct answer? It differs in that nextFloat() returns a
random number in the interval 0...1, so it does the same thing as
getFloat(0, 1).  See
https://wiki.php.net/rfc/randomizer_additions#nextfloat

A) The problem with nextFloat() is that the name creates a false
expectation. Take a look at the following code:
```
$randomizer = new \Random\Randomizer();
$a = $randomizer->getFloat(100, 200); // number between 100..200
$b = $randomizer->nextFloat(); // another number between 100..200 ???
```
One would expect that in `$b` there would be a number in the interval
100..200 again, but surprisingly not, there will be a number in the
interval 0..1.

B) When trying to think of a more appropriate name (e.g.
`getFloat01()` ?), I find that the simple `getFloat(0, 1) is concise
and succinct enough. If it were really useful to have a method that
returns numbers in this interval, wouldn't it be better to give the
$min and $max parameters the default values of 0 and 1, and thus call
`getFloat()` directly?

C) PHP 8.3 is still in testing and this change can be made. If it is
not done now, it will never be done and programmers will have to use
and also read unintuitive APIs for years. Similarly, in the days
before PHP 8.0 was released, I suggested changing PhpToken::getAll()
to today's tokenize() and there was no problem with that
https://bugs.php.net/bug.php?id=80328

D) There are libraries in other languages (Java, ASP.NET, etc.) that
also use methods named next() to generate numbers. This is perfectly
fine. The point is that they don't also use methods named get() in the
same time. The problem I am pointing out is that methods differing in
the prefix get/next differ only in the interval from which they return
numbers. You won't find this in any other language.

Thank for your time

DG