Front page | perl.perl5.porters |
Postings from August 2016
Re: Internals:: undocumented
From: Sawyer X
August 13, 2016 18:10
Re: Internals:: undocumented
Message ID: email@example.com
We have quite a few questions that we raised here, but I'll focus on two:
1. Should Internals:: be documented?
2. Should Internals:: namespace exist?
I agree that removing Internals:: namespace makes sense, in the steps
Yves suggests, but along Aristotle's direction ("poor person stuck with
the code" is quite the compelling argument, IMHO). However, if we want
to make the core more approachable and more understandable (both to
current hackers and new hackers), documenting what we have (even if only
for internal use) is on the table.
Thus, the first question can be rephrased as "Should the functions [only
currently] in Internals:: be documented?" - I would say yes. Then
slapping a nice "We do not assure compatibility of these functions. Use
at your own risk. If they provide something you cannot do otherwise or
do not know how, let us know."
When someone (outside core) uses an internal functions, they might not
know how to do it properly (Lack of documentation? Bad documentation?)
or they need an interface that does not officially exist (and perhaps we
should add it) or they are doing something wrong (perhaps also a
documentation problem on how to do it properly). At least the first two
we can try and address.
On 08/08/2016 09:36 PM, Aristotle Pagaltzis wrote:
> * demerphq <firstname.lastname@example.org> [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
> over time.
> 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?