[swift-evolution] [Guidelines, First Argument Labels]: Prepositions inside the parens

[Dave Abrahams]

on Tue Feb 09 2016, Xiaodi Wu <swift-evolution at swift.org> wrote:

> I'm having trouble with this example in 3(a):
> ```
> x.loadValues(forKeys: ["fox", "box", "lox"])
> ```
>
> Based on the preceding discussion, I understand that the above is
> preferred by the working group over the following:
>
> ```
> x.loadValuesFor(keys: ["fox", "box", "lox"])
> ```

More than being compelled by that specific example, when we looked
through how Cocoa imported with splitting basenames both before and
after prepositions, it became immediately obvious that on the whole, it
was much better to split before the preposition.

> Going by the guidelines, though, it seems like the first option is
> also now preferred by the working group over the unlabeled version
> below (which admittedly is only an option because 'keys' is not
> duplicating type information):
>
> ```
> x.loadValuesForKeys(["fox", "box", "lox"])
> ```

Yes, on balance, that's the direction we are leaning.

> Is it really the case that the first option is preferred over the
> third? It does look as though it is, based on this in the diff:
> ```
> - func respondWith(data: Data)
> + func respond(withData data: Data)
> ```

Yes.

> Whichever one is preferred, could the guidelines be clarified in that
> respect? 

Yes.

> Also, what of the guideline not to repeat type information?  

It

> For example, why isn't the method above `func respond(with data:
> Data)`?

It should be, AFAICT.  I think there's a complicated set of importer
heuristic interactions at work here, and the heuristics aren't getting
the best answer in this case.

> On Tue, Feb 9, 2016 at 1:18 PM, Dave Abrahams via swift-evolution
> <swift-evolution at swift.org> wrote:
>>
>> Hi everybody,
>>
>> Having looked at some examples, the API guidelines working group members
>> that were present this morning agreed we really want prepositions inside
>> the parentheses of method calls.
>>
>> Here are some results for the importer; we're still tuning some of the
>> heuristics but overall we feel very good about the preposition
>> placement:
>>
>>   https://github.com/apple/swift-3-api-guidelines-review/commit/da7e512cf75688e6da148dd2a8b27ae9efcb8821?diff=split
>>
>> Note that this is not final wording, but here are the guidelines we're
>> working with for first argument labels:
>>
>> A. Try to form a grammatical phrase including the first argument and
>>    describing the primary semantics at the call site.
>>
>> B. The first argument gets a label when and only when:
>>
>>    1. It does not form part of a grammatical phrase describing the
>>       primary semantics.  For example,
>>       ```
>>       x.dismiss(animated: y)
>>       ```
>>       [more examples needed]
>>       Note that parameters with defaults never describe the primary
>>       semantics. so are always labeled.
>>       ```
>>       func invert(options options: SomeOptionSet = []) // yes
>>       func invert(_ options: SomeOptionSet = [])       // no
>>       ```
>>
>>    2. The method is a factory method; such calls should mirror
>>       initializers, with no preposition.  For example,
>>       ```
>>       let x = UIColor(red: r, green: g, blue: b)
>>       let y = monitor.makeColor(red: r, green: g, blue: b)
>>       ```
>>
>>    3. It is part of a prepositional phrase
>>
>>      a. The label normally starts with the preposition.
>>         For example,
>>         ```
>>         x.move(from: a, to: b)
>>         x.loadValues(forKeys: ["fox", "box", "lox"])
>>         ```
>>      b. ...unless the preposition would break a very tight association
>>         between parameters:
>>         ```
>>         x.moveTo(x: a, y: b)
>>         ```
>>         [encourage grouping parameters into higher-level concepts,
>>         e.g. Point, in these cases]
>>
>>
>>
>> Feedback most welcome, of course.
>> --
>> -Dave
>>
>> _______________________________________________
>> swift-evolution mailing list
>> swift-evolution at swift.org
>> https://lists.swift.org/mailman/listinfo/swift-evolution
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

-- 
-Dave