Front page | perl.perl5.porters |
Postings from August 2016
Re: Internals:: undocumented
Thread Previous
|
Thread Next
From:
demerphq
Date:
August 8, 2016 14:43
Subject:
Re: Internals:: undocumented
Message ID:
CANgJU+Ve7pQMbHvkzbeenNANMmJ6MUsfku=UN2mUW-6UoJ998g@mail.gmail.com
On 8 August 2016 at 16:11, Chad Granum <exodist7@gmail.com> wrote:
> The downside to not documenting them in that there is no explanation as to
> why they are bad to use.
I personally subscribe to the view that using undocumented functions
of any sort is always bad. (Which does not mean I don't do it from
time to time when circumstance requires me to.)
> I myself used Internals::SvREFCNT(), I found some
> documentation that said Internals:: should not be used, but no real reason
> why except that it may change. I then noticed that Internals::SvREFCNT() was
> used in places that made it VERY unlikely it would ever be removed/renamed.
That is a most unsafe assumption.
> So I just went ahead and used it, and did so until others eventually found
> out and convinced me to stop.
See, and that for an undocumented function. Documenting them IMO would
only magnfiiy this effect. People would read what they do, decide
they will do it anyway, and then whine, even though we said they
couldnt use it in the first place. And other people would argue that
their whine has a point, and we would have a big bun fight about it
when someone wanted to change it.
> I don't remember the reasons I was given that convinced me to stop using it.
I hope it boiled down to "using undocumented functions is unsafe, and
inherently not-future-proof code", possibly with a side serving of
"you shouldnt diddle perl internals unless you are a core hacker".
> I wish I did so that I could propose we add them as part of the
> documentation. This is precisely why the namespace should be documented,
> more opportunities for warnings. An opportunity to provide reasons to avoid
> using them as well.
I think it is much much better they don't exist. Or exist in much saner forms.
>
> -Chad
>
> On Sun, Aug 7, 2016 at 2:34 AM, Sawyer X <xsawyerx@gmail.com> wrote:
>
>> Documentation should not imply support. We can
>> document it clearly for other core developers and note *very* clearly
>> that it is unsupported.
Unfortunately even when we make something warn that is unsupported
people still consider it unkind when we remove it or change it.
Documenting something that shouldn't exist merely calls attention to
its existence and promotes its use, whatever we say about using it.
I mean Chad's post is a perfect example. Someone who decides to use a
completely undocumented function despite the fact that it is in a
namespace like Internals.
You can imagine the IRC chatter when Internals was originally created:
"Dang, i need a way to test the refcount is being set properlyt"
"expose SvREFCNT() via XS?"
"sure, but what namespace?"
"Internals maybe?"
"Good idea. That seems pretty self-documenting that it shouldn't be
used except by the internals"
cheers,
Yves
--
perl -Mre=debug -e "/just|another|perl|hacker/"
Thread Previous
|
Thread Next