[swift-evolution] When to use argument labels (a new approach)

[Dave Abrahams]

> On Feb 4, 2016, at 12:10 AM, Brent Royal-Gordon <brent at architechies.com> wrote:
> 
>> I believe everything you've written here is actually expressed, in
>> practice, by the guidelines I've suggested.  I went through many of the
>> same thought processes in working the guidelines out.  The trick is to
>> capture these thoughts in something simply stated that has the right
>> effect.  If you think the guideline I suggested doesn't have the right
>> effect, please demonstrate a case where your thought process would lead
>> to a different API choice.
> 
> I think our positions are basically compatible; I simply find an explanation like this useful to understand *why* the rules are as they are. Many of the objections and alternative proposals I've been seeing don't seem to be informed by this philosophy.
> 
> I'm wondering if we should write up a rationale for the API guidelines as a design document that people can optionally read to help them understand the guiding philosophy behind the API guidelines.

Yeah, or there can be a section in the guidelines, or we can find another way to integrate rationale.  That should definitely be available somehow if people find it helpful.

> (I also wonder if introducing the concept of an option in a more explicit way might clarify some rules; for instance, the rule about giving the first parameter a label if it's defaulted is really about giving it a label if it's an *option*.)

I think it would possibly clarify the *rationale* behind some rules, but that's not the same as stating the rule clearly.  The fewer specific guidelines and angles you're required to use to analyze any given API design scenario, the better.  If we can clearly define what "option" means and replace some other criterion with that one, then it could be an improvement, but I don't see a clear path from here to there.