<html><head><meta http-equiv="Content-Type" content="text/html charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><br class=""><div><blockquote type="cite" class=""><div class="">On Feb 11, 2016, at 2:33 AM, Radosław Pietruszewski via swift-evolution <<a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><meta http-equiv="Content-Type" content="text/html charset=utf-8" class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class=""><blockquote type="cite" class="">Hi everybody,<br class=""><br class="">Having looked at some examples, the API guidelines working group members<br class="">that were present this morning agreed we really want prepositions inside<br class="">the parentheses of method calls.</blockquote><br class=""></div><div class="">I find that… surprising.</div><div class=""><br class=""></div><div class="">Between these two (sorry to repeat the same example again):</div><div class=""><br class=""></div><blockquote style="margin: 0 0 0 40px; border: none; padding: 0px;" class=""><div class="">func trackWith(trackID trackID: CMPersistentTrackID) -> AVAssetTrack?</div><div class="">func track(withTrackID trackID: CMPersistentTrackID) -> AVAssetTrack?</div><div class=""><br class=""></div></blockquote>#1 seems nicer and clearer to me. Having “with” as the first word glued to a parameter label looks bizarre to my eyes:<div class=""><br class=""></div><div class="">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.</div><div class=""><br class=""></div><div class="">Another reason I don’t like this, say we have:</div><div class=""><br class=""></div><div class=""><span class="Apple-tab-span" style="white-space:pre"> </span>a.tracks(withMediaType: b, composer: c)</div><div class=""><br class=""></div><div class="">This no longer looks symmetrical across the parameters. First parameter has label “with”, second doesn’t. The previous version:</div><div class=""><br class=""></div><div class=""><span class="Apple-tab-span" style="white-space:pre"> </span>a.tracksWith(mediaType: b, composer: c)</div><div class=""><br class=""></div><div class="">Didn’t have that problem.</div><div class=""><br class=""></div><div class="">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”:</div><div class=""><br class=""></div><div class=""><span class="Apple-tab-span" style="white-space:pre"> </span>a.tracks(withMediaType: b, andComposer: c)</div><div class=""><br class=""></div><div class="">To avoid this weird-looking construct where the first parameter has a starting preposition, and other parameters don’t. Again:<br class=""><div class=""><div class=""><br class=""></div><div class=""><span class="Apple-tab-span" style="white-space:pre"> </span>a.tracksWith(mediaType: b, composer: c)</div><div class=""><br class=""></div><div class="">Doesn’t have this problem, because while the method name part ends with “With”, the parameters are consistently just nouns.</div><div class=""><br class=""></div><div class="">So -1 from me on this. Moving prepositions inside parens look like a step back from the Part DEUX Proposal.</div><div class=""><br class=""></div><div class="">Would you mind elaborating on the working group's rationale for moving prepositions inside parens?<br class=""></div></div></div></div></div></blockquote><br class=""></div><div>A couple of reasons that I, personally, found motivating (some of which came up on this list before):</div><div><br class=""></div><div> (1) A prepositional phrase is a grammatical entity, and we probably shouldn’t split a grammatical phrase across ‘(‘.</div><div> (2) It seemed to separate “what the method does” (base name) from “how it does it” (argument label) more effectively.</div><div> (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.</div><div><br class=""></div><div>… and we spent a while looking at the diff of Cocoa, here:</div><div><br class=""></div><div><span class="Apple-tab-span" style="white-space:pre"> </span><a href="https://github.com/apple/swift-3-api-guidelines-review/commit/b22b62bb98e5d44b2528b237d18efe96bf2940d6" class="">https://github.com/apple/swift-3-api-guidelines-review/commit/b22b62bb98e5d44b2528b237d18efe96bf2940d6</a></div><div><br class=""></div><div><span class="Apple-tab-span" style="white-space:pre"> </span>- Doug</div><div><br class=""></div><br class=""></body></html>