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

[Dave Abrahams]

on Wed Feb 10 2016, Matthew Judge <matthew.judge-AT-gmail.com> wrote:

> On Tue, Feb 9, 2016 at 2: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.
>>
>
> I assume that A is intended to cover:
>
> a.addObserver(b) // yes
> a.add(observer: b) // no

I don't know what you mean by "cover." It isn't intended to assign the
"yes/no" decision to those; they both form (the same) grammatical phrase
at the call site.  The choice between those two is governed by B, below.

> I believe I can read this behavior into A by inferring "a grammatical
> phrase including [the base name and] the first argument" but I want to make
> sure this is the intent.
>
>>
>> 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)
>>       ```
>>
>
> If rule B.2 didn't exist
>
> let y = monitor.makeColor(red: r, green: g, blue: b)
>
> would still have the first argument labeled by B.1 wouldn't it? 

Yes, but you could have done this grammatically, as 

     let y = monitor.makeColorHavingRed(r, green: g, blue: b)

That's what B2 is designed to prevent.

> (Though without this rule, the guidelines wouldn't be clear on whether
> or not to include prepositions in the argument labels.)
>
>>
>>    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]
>>
>>
> This seems clear and straightforward to apply. The only place where
> this isn't totally clear is when there are multiple prepositions (as
> highlighted in Jacob's response), 

Multiple prepositions before the first argument?

> but I think B.3 provides the right level of guidance... much more
> detail will start being too many guidelines and special cases.

Thanks!
-- 
-Dave