develooper Front page | perl.perl5.porters | Postings from August 2016

Re: Internals:: undocumented

Thread Previous | Thread Next
From:
Chad Granum
Date:
August 8, 2016 14:11
Subject:
Re: Internals:: undocumented
Message ID:
CAJFr3kuE17hvLYRY4K6zS6ep+i_YKFM220cDj1MReDjhpotjWA@mail.gmail.com
The downside to not documenting them in that there is no explanation as to
why they are bad to use. 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. So I just went ahead and used it, and did so until others
eventually found out and convinced me to stop.

I don't remember the reasons I was given that convinced me to stop using
it. 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.

-Chad

On Sun, Aug 7, 2016 at 2:34 AM, Sawyer X <xsawyerx@gmail.com> wrote:

> On 08/06/2016 03:39 PM, Tony Cook wrote:
> > On Sat, Aug 06, 2016 at 09:05:23AM -0400, James E Keenan wrote:
> >> What is Internals?
> > Internals is deliberately undocumented, unsupported.
>
> Not documenting as a form of keeping possible users away feels like
> security by obscurity. Documentation should not imply support. We can
> document it clearly for other core developers and note *very* clearly
> that it is unsupported.
>

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