Front page | perl.perl5.porters |
Postings from August 2016
Re: Internals:: undocumented
From: Aristotle Pagaltzis
August 8, 2016 19:36
Re: Internals:: undocumented
Message ID: 20160808193610.GA8024@plasmasturm.org
* demerphq <email@example.com> [2016-08-08 15:36]:
> Internals:: shouldn't exist as a namespace. That it exists, and what
> it contains is wrong and evil.
> Documenting wrong and evil just makes things worse, because people
> might actually read the documentation and decide to increase the
> amount of wrong and evil in the universe.
But then there is the poor bastard who had someone else’s code dropped
in their lap, is left holding the bag for whatever their predecessor
did, and now has to figure out what the darn thing does. What has s/he
done to deserve the silent treatment?
> Instead, even if it is short term more work we should act to reduce
> the amount of wrong and evil in the universe. The way to do so here
> is to get rid of the Internals:: namespace.
Agreed, but don’t kid yourself about the time frame: grep.cpan.me finds
Internals:: in “more than 1000 distributions”. This horse has been gone
from the barn long enough that it has sired a couple foals. :-(
> 0. We should move hv_clear_placeholders() out of Internals:: and put
> it in Hash::Util.
> 1. We should remove SvREFCNT() from Internals::, and replace it with a
> set/get pair, possibly which live in different namespaces. I don't
> think any Perl code outside of our test suite has any reason to ever
> set a refcount.
> 2. We should remove SvREADONLY() from Internals, and replace it with a
> set_readonly() function and a is_readonly() function which is injected
> into the namespaces where it is used, for instance Hash::Util and
I don’t disagree in spirit, but it’s a huge chunk of work to turn around
the entire ecosystem at this point, which seems like a distraction from
the real goal of removing the wrongs and evils.
My proposal would be to provide the same alternatives you suggest and to
advertise them as the right thing to use in the Internals:: docs of each
function (so people can start moving their code off of it, and people
who look up the functions for the first time are redirected to the right
choices), but not remove the Internals:: stuff outright – rather, make
the evil parts of the SvFOO functions whine when used.
Then, after some reasonable time not too far off, the evil bits go away.
Of course, nothing new should ever be put in there again.
At that point, Internals:: is no longer evil, just crufty, meaning the
urgency to excise it from mountains of code is gone. The docs and the
usual community advocacy can take over the job of turning people away
That way the wrong and evil can be be done away with sooner than would
be possible any other way, while also leaving the ecosystem as long to
turn over as it needs.
> I don't think any Perl code outside of our test suite has any reason
> to ever set a refcount.
Maybe it could be put in an XS module that is built but not installed,
so that perl’s test suite can use it, but after that it’s unavailable?
Or some such?
Aristotle Pagaltzis // <http://plasmasturm.org/>