Front page | perl.perl5.porters |
Postings from November 2016
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. -zeframThread Previous | Thread Next