Re: [RFC] [discussion] Correctly name the rounding mode and make it an Enum

From: Date: Mon, 01 Jul 2024 20:18:37 +0000
Subject: Re: [RFC] [discussion] Correctly name the rounding mode and make it an Enum
References: 1 2 3 4 5 6  Groups: php.internals 
Request: Send a blank email to [email protected] to get a copy of this message
Hi

please apologize the delay in getting back to you. I was absolutely swamped with mailing list mails, other work and I didn't want to give a reply that I did not give any thought.

On 6/19/24 21:14, Claude Pache wrote:
Second, “TowardsPositiveInfinity” is just a mouthful synonym for “Up”. You could just name it: Round::Up
Except that it isn't and both the RFC and the two fine folks who already replied explained why.
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.
Please note that the comparison was not made against the corresponding “Half” mode, but rather that the term “Up” is needlessly ambiguous. As I've also replied to Jordan: The RFC intentionally does not use the Up terminology (except to refer to the existing constants, which unfortunately use that terminology).
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 “half-*” mode, and to erroneously interpret it as Round::HalfUp (or, its synonym Round::HalfTowardsPositiveInfinity).
That is a fair concern. We shortly discussed splitting the enum into one "MidpointRoundingMode" and one other enum for the directed rounding modes, but we felt that it did not reliably solve this problem either. At least with a single enum all the 'Half' modes would appear in autocompletion.
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 “Half” token that immediately indicate the right interpretation.
Right.
So, the best way to disambiguate Round::Up from Round::HalfUp, is not to replace “Up” with some creative synonym, but to add a distinctive token that plays the role of — and contrasts with — “Half”. I don’t know if the following suggestion makes sense for you, but it is the one I have found: Round::FullUp
You might have misunderstood my email. The concerns were not that HalfTowardsZero is too similar to TowardsZero, but rather that HalfTowardsZero is too similar to HalfTowardsEven, because they share the same 11-character prefix.
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’t know English, you will not grasp the metaphor and have to just learn it. However, whatever other name you invent, you *have* to learn “ceil” 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* “ceiling”.
There is precedent for an "infinity-based" naming in other programming languages. The most mainstream one is probably C#: https://learn.microsoft.com/en-us/dotnet/api/system.midpointrounding?view=net-8.0 But there is also MATLAB: https://de.mathworks.com/help/matlab/ref/round.html#mw_e51282fd-7461-4bab-9f38-6106551bb8b2 We can even find precedent in PHP itself. The GMP extension already has rounding mode constants GMP_ROUND_PLUSINF and GMP_ROUND_MINUSINF: https://www.php.net/manual/en/gmp.constants.php And to add some anecdata: Just a few days ago I fixed a bug where the floor() function was incorrectly used where rounding towards zero was desired, resulting in incorrect results for negative numbers. The Ceiling / Floor / Up / Down naming is needlessly ambiguous, especially for non-native speakers.
For the same reason, Round::TowardsZero (suboptimal, because confusable with Round::HalfTowardsZero) could be replaced with: Round::Truncate.
While I think that Truncate is reasonably clear, breaking the mapping between the midpoint modes and the directed rounding modes just for this case does not appear useful. Best regards Tim Düsterhus

Thread (27 messages)

« previous php.internals (#124159) next »