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

Thu Feb 11 12:11:23 CST 2016

> On Feb 11, 2016, at 2:33 AM, Radosław Pietruszewski 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.
> 
> 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?

I think this one particular function is possibly the worst case in the entire API. Neither “track” nor “trackWith” is a particularly good function name. But as I mentioned in a previous post, I think, for many of the Foundation functions, moving the prepositional phrase into the argument label actual aids clarity slightly. I was surprised that I ended up liking it, but I do.

> 
> #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.

I sympathize with this. My attitude about it, though, is that we would normally only say “with” before the first item in a list, and dropping the “and” from before the final item is a fairly minor offense against the English language. I personally don’t think clarity is really harmed. It might help to add specific guidance that using “and” in these cases is discouraged.

—CK

> 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 <mailto: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 <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 <mailto: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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160211/2e1612d1/attachment.html>