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

[Dave Abrahams]

on Wed Feb 10 2016, Matthew Judge <swift-evolution at swift.org> wrote:

>> On Feb 10, 2016, at 18:17, Dave Abrahams <dabrahams at apple.com> wrote:
>> 
>> 
>>> 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.
>
> By cover I meant assign the "yes/no" decision. So because the first
> argument is part of the primary semantics, it doesn't get an argument
> label (per B.1) and the word observer needs to be in the base name so
> as not to change the semantic meaning.

Correct.

>>> 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?
>
> Yes, before and including the first argument label. For example (from Jacob's response):
>
> comparePositionInDecodeOrderWithPosition(of cursor: AVSampleCursor) -> ComparisonResult
>
> Jacob suggests spelling it:
>
> comparePositionInDecodeOrder(withPositionOf cursor: AVSampleCursor) -> ComparisonResult
>
> I agree that Jacob's spelling is better, but not enough better to
> justify additional guidelines about prepositions.

I think I agree that it's better.  I think I also agree that  we could
avoid complication in the guidelines by leaving the
multiple-prepositions case unspecified and letting the judgement of API
designers come up with the right answer.  However, we *are* looking into
the question of whether "Of" should get special treatment.  It seems
like it may *always* be worse to put the parenthesis before "of," even
when it's the only preposition:

     x.appendContents(of: y)
     x.appendContentsOf(y)   // I like this one a *lot* better

>>> 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
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

-- 
-Dave