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

[Douglas Gregor]

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

A couple of reasons that I, personally, found motivating (some of which came up on this list before):

  (1) A prepositional phrase is a grammatical entity, and we probably shouldn’t split a grammatical phrase across ‘(‘.
  (2) It seemed to separate “what the method does” (base name) from “how it does it” (argument label) more effectively.
  (3) Related to (2), it pulled out more method families, where we had the same basic operation (described by the base name) and the argument labels differentiated how we got to that result.

… and we spent a while looking at the diff of Cocoa, here:

	https://github.com/apple/swift-3-api-guidelines-review/commit/b22b62bb98e5d44b2528b237d18efe96bf2940d6

	- Doug


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