develooper Front page | perl.perl5.porters | Postings from July 2017

Re: [perl #131685] Rename utf8::is_utf8() (and other functions)

Thread Previous | Thread Next
From:
Karl Williamson
Date:
July 13, 2017 04:54
Subject:
Re: [perl #131685] Rename utf8::is_utf8() (and other functions)
Message ID:
8f707bd8-10cd-0faa-558e-fae02fc61c04@khwilliamson.com
On 07/12/2017 12:36 AM, H.Merijn Brand wrote:
> On Tue, 11 Jul 2017 10:41:37 -0700, "Father Chrysostomos via RT"
> <perlbug-followup@perl.org> wrote:
> 
>> On Tue, 11 Jul 2017 00:55:51 -0700, davem wrote:
>>> On Mon, Jul 10, 2017 at 12:45:48PM -0400, Sawyer X wrote:
>>>> Does anyone have any comments on this? Tony, Dave, Zefram? *Karl*? :)
>>>
>>> My opinion on this sort of proposal (and it's an opinion which has gotten
>>> stronger over time (*)) is rarely/never to add a new alias name to an
>>> existing function.
>>>
>>> Alias names just increase the cognitive load. If the old names were
>>> confusing, having more names will just increase the confusion.
>>>
>>> Before, you would have to remember that a particular function foo() is
>>> badly named and doesn't do what you might expect it to do, based solely on
>>> the name.
>>>
>>> Afterwards, you have to remember that that are two functions foo() and
>>> bar(), one is deprecated (which one?), one is badly named (which one?),
>>> but they both do the same thing (Or do they? Sigh. Let's check the
>>> documentation one more time).
>>>
>>> Life is now harder.
>>>
>>> (*) My opinion firmed over AvFILL(). It was a weird name, but I was used to
>>> it. Now I can never remember what the new alias is called (just looked
>>> it up - av_top_index()). In hindsight, I would have voted against adding
>>> av_top_index.
>>
>> I agree with everything you have said.  I brought up the same
>> objection when this proposal was first put forward, but I thought I
>> had lost the debate.  Well, at least there are two of us now. :-)
> 
> Count me in: three. I like the way Dave has written down my feelings :)
> 

I guess we have a fundamental disagreement about language design and the 
direction Perl should go, which makes me sad.

The point of adding synonyms for deceptively-named functions and macros 
is to make life easier overall.  Forbidding new better-named synonyms 
for problematically named things forces everyone who comes along to deal 
with the gotchas and cognitive load that those people already here have 
had to deal with.  By creating better named things, those people can 
largely avoid these problems.  This allows them to work more 
efficiently, avoiding traps, and with less cursing Perl.

Unless Perl is close to death, the number of people who are going to 
come along before it does die dwarfs the number who are already expert. 
   Some people are knowledgeable in parts of Perl, but not all.  They 
also gain if gotchas get removed before they have to deal with them.

Specifically about av_top_index, I don't believe that it is so poorly 
named that you have to keep consulting the documentation as to what it does.

It came about not because of AvFILL, but because of the already-existing 
synonym, the evilly named "av_len".  This name implies it gives a 
length, but in fact it is one-off from that.  av_top_index, though 
cumbersome, accurately indicates what it returns.

Using av_len is a bug waiting to happen.  It is a foreseeable problem. 
I believe that it would be unethical to not create a non-deceptive 
alternative.  It's kind of like a safety recall.

Writing code using deceptively named things or with poor API's is slower 
and more error prone.  Every time you use one, you have to get out of 
your mental pipeline and recall that this is a gotcha, and have to 
figure out how it is a gotcha and how you have to compensate.  You are 
effectively flushing your mental instruction cache.  In the case of 
av_len, you have to remember which way is the off-by-one problem here.

Code reviews also are affected.  It is just too easy to read the thing 
and forget that it doesn't do what you would want.

In researching the issue back when av_top_index was created, I found 
published modules that used av_len, as its name implies, as a length. 
Others undoubtedly had caught the problem earlier, say through their 
unit testing.

But all this could be avoided by the code using a non-deceptive name. 
Hopefully, the coder won't even be aware that there exist deceptive ones 
for hysterical reasons.

It is foreseeable that av_len is going to cause problems.  It would be 
irresponsible of us to not create a non-deceptive synonym when it is so 
easy to do.

No one was really happy with "av_top_index" as a name.  So AvFILL was 
retained in the core.  All occurrences of av_len were removed.  If we 
could have come up with a short, pithy synonym, we would have replaced 
AvFILL as well, and then people looking at the core would have seen that 
and gotten used to it, and over time the memory of the less well-named 
versions would have faded.

Writing good APIs is hard.  I have flattered myself at times into 
thinking I'm good at it.  Maybe I am actually good, but if so, I'm still 
not good enough.  And few, if any, are.  If we have a poor API in some 
area, we should not tie our hands and say tough to all those people who 
come along later, and give them more reason to use some other language

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About