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

[Radosław Pietruszewski]

> 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

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