Clarity over brevity? Default methods to more descriptive names? about swift-numerics HOT 15 CLOSED

The short/common names were approved as part of SE-0246, so I won’t rush to wholesale change them.

In particular, where they match what is written normally in math, we should definitely keep the short name. Where it’s only a computer term we should think more carefully (expm1, log1p, atan2, etc—you may notice I already renamed the first two). I don’t want a lot of churn on this, though, so any renaming would be very slow and deliberate.

from swift-numerics.

log1p has severe discoverability problems. Most users see it, say, "I don't know what it means, I'll ignore it," which then results in bugs because they should have been using it. Even if they decide to search it, they get a lot of results searching for it, but almost none of them clearly tell you why or when you should use it. They just say something like "Computes ln(1 + x)." The cure is almost worse than the disease. I'm not really wedded to the new name, but log1p isn't anything to write home about either, and at least the new one is more clear at the point of use to someone who doesn't know about the function.

People confuse the argument order of atan2 all the time. Labelling them helps, but it's not obvious that we can't do something even better. I haven't jumped to change it, but I'm open to the possibility.

from swift-numerics.

@stephentyrone At the time, my suggestion was to have ulp(1) as the only spelling. But yes, I agree that what we have is better than epsilon.

Aside: I think ulp and ulpOfOne are rather a good example here in illustrating what we mean by "clarity." It is an improvement from epsilon precisely because it cannot be misinterpreted to mean anything but what it is. I don't think we need to recite the entire chain of reasoning here, but suffice it to say that I am thankful that we did not attempt to name it unitInTheLastPlaceOfOne.

I'm not arguing the general principle that we should rectify what is broken when there is a solution: it is an enormous opportunity afforded to us by the fact that these are to be new APIs in Swift. I also entirely agree with being very circumspect.

I'm specifically bringing up the question of what to do about log1p and expm1. No, they aren't set in stone. I would go so far as to argue that even if a term as well established as 'sine' had the same problems with _mis_understanding as does epsilon, that we should absolutely consider changing the name, but that's not what is at issue here.

I get why you have opinions about the merits of log1p versus logp1. This makes sense when one is as involved as you are in the field; for you, this is a live issue. (And yes, I too have chuckled in the past about the thought of log101p.) But for virtually anyone else, it is rather more akin to having the opinion that "sine" is a Latin mistranslation of the Arabic, and therefore we ought to call it the half-chord.

from swift-numerics.

Re:

cosh -> hyperbolicCosine or cosineHyperbolic etc.

I'd say there is a certain value in persisting common names of the functions which are corresponding to the derived trigonometric functions.

from swift-numerics.

Yeah trigonometric functions do have standard short names, so maybe those ought to be kept and not have a verbose version. But I think erf can have both, were erf is just a shorthand syntax wrapper function calling errorFunction.

from swift-numerics.

@xwu Sure, but do you want to rename .ulpOfOne back to .epsilon? I think you'd agree that it's a better name. So improvement is possible, these things aren't totally set in stone. It's just that we should be very circumspect about it.

I'm more OK with toying with the log1p and expm1 names than most other functions for a couple reasons:

• they're infrequently used
• there's a trainwreck coming for the "standard" names, in the form of exp2m1, exp10m1, log..21p??! We are extremely lucky in that we're naming these at a time when we can see this coming. The current C proposal is to change log1p to logp1*, and add log2p1, log10p1. Meanwhile, C++ recently proposed log2p1 for a completely different operation (https://en.cppreference.com/w/cpp/numeric/log2p1), which thankfully I and a few other people were able to flag before the standard was finalized.

These names are "standard" but do not generalize well, and they are going to need to generalize in the next decade. We need to design with that in mind, and the fact that the bulk of the computational math community has never given these issues adequate thought doesn't excuse us from doing it.

(*) this name is worse in every way, except that it avoids log21p and log101p. We should do better.

from swift-numerics.

Yeah, about those renames.

I don't see why a standard computer name should get less respect here than a standard math name. By now they have been around for the entire working lifetime of most users. I'm not sure it buys us much to differ from those unless there's active confusion (e.g., atan2(y:x:)). There's thousands more about log1p available on a simple search than for any other name we can come up with.

Clarity does not mean "more descriptive." It means exactly what it says: it should be clear what the function actually does. If there is only one way to interpret the meaning of "erf," then it is crystal clear.

from swift-numerics.

They just say something like "Computes ln(1 + x)." The cure is almost worse than the disease. I'm not really wedded to the new name, but log1p isn't anything to write home about either, and at least the new one is more clear at the point of use to someone who doesn't know about the function.

With the name log(onePlus:), the same cure is now delivered in the form of the name.

And now that it's in source, it's an invitation for users who don't understand the purpose of the function to refactor log(onePlus: x) to log(1 + x)--after all, the latter is terser and arguably more readable, and by construction we're talking about someone who doesn't understand the purpose of the original function.

I'm skeptical that the issue of discoverability here can be solved by innovations in name, in part because I have no doubt that others have tried throughout many years--yet the original name remains standard. What we do lose for sure is discoverability for those who do know about the function and are coming from other languages.

from swift-numerics.

I have no doubt that others have tried throughout many years

There's copious evidence to the contrary on this point. The complete set of languages that have meaningfully tried to innovate on math operation naming in a vaguely thoughtful manner is basically Fortran, C*, and Julia. As evidence, consider the absolutely horrible cargo-culting of epsilon between most languages--that's a much bigger problem, and one that almost no language has even tried to solve.

(*) C mostly phoned it in

from swift-numerics.

C#: https://github.com/dotnet/corefx/issues/16428

from swift-numerics.

@xwu Ah, yes, the language that managed to make epsilon worse (https://docs.microsoft.com/en-us/dotnet/api/system.double.epsilon?view=netframework-4.8) =)

from swift-numerics.

@stephentyrone Yes, amusing! Also, kind of illustrating my point:

Whatever your judgment of how C# tackled epsilon, you have to concede that they did indeed try to solve the problem. The danger of trying to make things better is that there is a risk of making them worse!

Virgil has a beautiful phrase in the Aeneid of which I try to remind myself every day: aegrescitque medendo (roughly, "and by healing he grows more sick").

from swift-numerics.

What we do lose for sure is discoverability for those who do know about the function and are coming from other languages.

This can be easily resolved by adding the declaration of the old name and marking it as obsolete. As a result, the IDE will display an error text with a proposal to use the new function naming design.

from swift-numerics.

I recall there being a similar debate during SE-0246's proposal on Swift Forums regarding the decision whether to maintain convention across other programming languages and keep the more confusing mathematical method names versus making the names more descriptive to fit with Swift's design philosophy. If you are interested on reading about what some people had to say regarding the topic, I would check out SE-0246's initial proposal on Swift Forums.

from swift-numerics.

I'm closing this as a settled question now that RealModule and ComplexModule are binary stable with the existing names.

from swift-numerics.