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

Re: RFC: core sub signature introspection

Thread Previous | Thread Next
November 24, 2016 08:21
Re: RFC: core sub signature introspection
Message ID:
Sam Kington wrote:
>So if e.g. you document a function as create_website($domain,
>$document_root) but implement it as create_website($hostname,
>$home_dir) that's a sign that potentially you haven't thought
>things through.

In that situation the different parameter names seem to be describing
different things.  It sounds like confusion over what the API actually is.
That is not at all what I'm talking about.

>Which use cases am I missing?

The different naming contexts (public documentation and implementation
internals) may require different levels of disambiguation, because they
have different sets of concepts among which to disambiguate.  For example,
suppose a sub takes a coordinate pair among its parameters.  The sub's
API may well be concerned with only a single point, described in a single
coordinate system, so plain "x" and "y" would be appropriate public names
for the parameters.  Those would be the names used in the documentation,
and if parameter name metadata is attached to the sub for hinting purposes
then that metadata would match the documentation.  But internally the sub
may be dealing with several coordinate pairs: multiple points involved
in the operation, and maybe multiple coordinate systems.  Plain "x"/"y"
would be ambiguous, so the parameters would need more explicit names,
such as "viewer_x"/"viewer_y".  Some naming conventions use different
letters for x/y coordinates in different spaces, so the coordinate pair
parameters could even be "u"/"v" internally.

Another situation that sometimes arises is that public parameter
names arise from a context that isn't even aware of the specific sub.
Consider an API that many classes implement, such as a file handle API.
The general API has only a general idea of the significance of some
parameters, and supplies names for them accordingly.  A specific class
implementing that API might have a more specific interpretation of some
parameters, reflected at least in its internal naming of them.  In those
cases there's a judgement call to make as to which set of names should
appear in the documentation (and public metadata) of the specific class.

It is sometimes the case that a parameter included for API reasons isn't
actually used by a sub, so the sub would prefer not to name the parameter
at all internally.  The reasons for including the parameter in the API
usually extend to establishing a name for it in the documentation.

It's also possible that documentation and implementation follow different
conventions for naming style.  This would be unusual if both come from
the same programmer, but collaborations sometimes throw up such clashes.
The resolution of the various consistency issues could result in something
publicly named "max_work_factor" while privately named "maxWorkFactor".

These situations are not the norm, of course.  It is usually viable for
the public and private names of parameters to match, and where viable
it is usually best to do so.  This is what makes it sensible to have
some option to automatically populate public parameter name metadata
from the internal declarations.  We just can't prescribe that they must
always match.


Thread Previous | Thread Next Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About