Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:123687
Content-Type: text/plain;
	charset=utf-8
Precedence: bulk
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3774.600.62\))
Subject: Re: [PHP-DEV] [RFC] [discussion] Correctly name the rounding mode and
 make it an Enum
In-Reply-To: <67d37d56-625f-4f80-805d-a5db2d3807bb@bastelstu.be>
Date: Wed, 19 Jun 2024 21:14:33 +0200
Cc: "Gina P. Banyard" <internals@gpb.moe>,
 Saki Takamachi <saki@sakiot.com>,
 Jorg Sowa <jorg.sowa@gmail.com>,
 php internals <internals@lists.php.net>
Content-Transfer-Encoding: quoted-printable
Message-ID: <0A9642EC-0FCC-4BC3-82C2-C6C968CD8D1C@gmail.com>
References: <9zUVZKaEYixjCLLhviQPYFQtSAEhsRMWL6xbKeogzAGsH-STebN9JqJxITAPVfdKTNu7gEs_m77OkIcOzaiscoajx8Hp8VWRKkhTTCPkGko=@gpb.moe>
 <6E690732-8BED-4A01-8385-648E7CEDFD9F@sakiot.com>
 <70f63dd2e0ba7959a9e3bb7fa68ce14a@bastelstu.be>
 <CJrCSLTp-erzdhSRTrFn2Ss0AoEpkkhqh7fnUrXgHyMfgNPkwXhpSeGsKdhV_ycUIqWhJWpWOxI0W8XGprR_O8iqSrVVWoBNiUUFMaZCNDY=@gpb.moe>
 <67d37d56-625f-4f80-805d-a5db2d3807bb@bastelstu.be>
To: =?utf-8?Q?Tim_D=C3=BCsterhus?= <tim@bastelstu.be>
From: claude.pache@gmail.com (Claude Pache)

Hi,=20

Naming is hard, for sure. Here is my review. I find the names mostly =
reasonable, except Round::PositiveInfinity and Round::NegativeInfinity. =
I will discuss Round::PositiveInfinity.

First:

> I've discussed this with Saki. In that case the `HalfEven` and =
`HalfOdd` modes would also need to be renamed to `HalfTowardsEven` and =
`HalfTowardsOdd`

For me, the implied preposition in `HalfEven` is =E2=80=9Cto=E2=80=9D, =
not =E2=80=9Ctowards=E2=80=9D. In other words, in the HalfEven mode, a =
half-number is replaced with the nearest even integer; it is not =
replaced with a integer *in the direction of* (or: *towards*) an even =
integer. So, `Round::HalfEven` is fine; but `Round::PositiveInfinity` =
does not make much sense to me, as the number is not rounded to +=E2=88=9E=
, but towards +=E2=88=9E.

-------

Second, =E2=80=9CTowardsPositiveInfinity=E2=80=9D is just a mouthful =
synonym for =E2=80=9CUp=E2=80=9D. You could just name it:

Round::Up

At this point, you may invoke either Hamming or Levenshtein and compare =
it negatively with `Round::HalfUp`. Yes there is a risk a confusion (and =
I do think that such a name is suboptimal for this reason), but the =
confusion is not just caused by the short Levenshtein distance. That =
brings to the most important part of my review.=20

-------

In my opinion, the most important criterion for a good name is:

The name must be clear for itself, not just when comparing it with other =
ones.

The problem with `Round::Up` (or `Round::[Towards]PositiveInfinity`), =
when you first encounter it, is that it is relatively easy to =
mistakingly assume that it is a =E2=80=9Chalf-*=E2=80=9D mode, and to =
erroneously  interpret it as `Round::HalfUp` (or, its synonym =
`Round::HalfTowardsPositiveInfinity`).

But that the converse is false: it is impossible to interpret =
`Round::HalfUp` as if it were `Round::Up` (or =
`Round::TowardsPositiveInfinity`), because of the distinctive =E2=80=9CHal=
f=E2=80=9D token that immediately indicate the right interpretation.

So, the best way to disambiguate `Round::Up` from `Round::HalfUp`, is =
not to replace =E2=80=9CUp=E2=80=9D with some creative synonym, but to =
add a distinctive token that plays the role of =E2=80=94 and contrasts =
with =E2=80=94 =E2=80=9CHalf=E2=80=9D. I don=E2=80=99t know if the =
following suggestion makes sense for you, but it is the one I have =
found:

Round::FullUp

---------

That said, I think that there is an even better option. I know you will =
not like it, but bear with me. I sincerely think that the best name is =
just:

Round::Ceiling

It is short, distinctive, and standard across the computing industry.

Yes, this name is idiosyncratic to English and not used in several other =
(natural) languages, and if you don=E2=80=99t know English, you will not =
grasp the metaphor and have to just learn it. However, whatever other =
name you invent, you *have* to learn =E2=80=9Cceil=E2=80=9D anyway, =
because you *will* encounter it sooner or later. Many common =
(programming) languages, including JavaScript, C++, Java, Python, have a =
`ceil` function. Even if you manage not to learn any of those and to =
code in PHP only, you are at risk to stumble on its built-in `ceil(...)` =
function, or its newly-introduced `bcceil(...)` variant.

Therefore, unless we find a name that is *really* good, I suggest to not =
fall into the NIH syndrome, and not to force users to learn another name =
*in addition to* =E2=80=9Cceiling=E2=80=9D.

---------

For the same reason, `Round::TowardsZero` (suboptimal, because =
confusable with `Round::HalfTowardsZero`) could be replaced with: =
`Round::Truncate`.


=E2=80=94Claude