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

[Dave Abrahams]

on Thu Feb 11 2016, Thorsten Seitz <swift-evolution at swift.org> wrote:

> Wouldn't rule 3b "unless the preposition would break a very tight association between parameters" apply, resulting in
>
> a.tracksWith(mediaType: b, composer: c)

I don't think so.  Maybe it could be expressed better, but the intent of
the “tight association” language is that the multiple parameters are
really part of a single abstraction that could be replaced by a single
type, e.g. (x:, y:) => Point.
   
> This would not be applicable to the unary variant, though...
>
> -Thorsten 
>
>> Am 11.02.2016 um 11:33 schrieb Radosław Pietruszewski via
>> swift-evolution
>> <swift-evolution at swift.org>:
>> 
>>> 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.
>> 
>> I find that… surprising.
>> 
>> Between these two (sorry to repeat the same example again):
>> 
>> func trackWith(trackID trackID: CMPersistentTrackID) -> AVAssetTrack?
>> func track(withTrackID trackID: CMPersistentTrackID) -> AVAssetTrack?
>> 
>> #1 seems nicer and clearer to me. Having “with” as the first word
>> glued to a parameter label looks bizarre to my eyes:
>> 
>> As far as I understand it, the whole reason to keep “with” etc in
>> many APIs was to make cases like this one clearer. Because “track”
>> as a name doesn’t tell you much. Someone said that having the method
>> name end with “With” creates a sense of suspense, and to me that was
>> precisely what was a good thing about it. It’s not just “track”,
>> it’s a “track with” — ooh, here come the criteria for the track!
>> Having removed “with” from the name itself, we lose, IMHO, the
>> clarity this word was supposed to bring in
>> initializer/getter/finder-like methods. And we still keep the word
>> later inside the parens, but to my eyes it no longer helps clarity,
>> just exists as a vacuous, needless word.
>> 
>> Another reason I don’t like this, say we have:
>> 
>> 	a.tracks(withMediaType: b, composer: c)
>> 
>> This no longer looks symmetrical across the parameters. First
>> parameter has label “with”, second doesn’t. The previous version:
>> 
>> 	a.tracksWith(mediaType: b, composer: c)
>> 
>> Didn’t have that problem.
>> 
>> I fear that people will take that as a signal that they should make
>> the whole method, including parameter labels, sound like an English
>> sentence and will start applying needless words like “and”:
>> 
>> 	a.tracks(withMediaType: b, andComposer: c)
>> 
>> To avoid this weird-looking construct where the first parameter has
>> a starting preposition, and other parameters don’t. Again:
>> 
>> 	a.tracksWith(mediaType: b, composer: c)
>> 
>> Doesn’t have this problem, because while the method name part ends
>> with “With”, the parameters are consistently just nouns.
>> 
>> So -1 from me on this. Moving prepositions inside parens look like a step back from the Part DEUX Proposal.
>> 
>> Would you mind elaborating on the working group's rationale for moving prepositions inside parens?
>> 
>> 
>> — Radek
>> 
>>> On 09 Feb 2016, at 20:18, 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
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

-- 
-Dave