<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></blockquote></div></div></blockquote><div><br class=""></div><div>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.</div><br class=""><blockquote type="cite" class=""><div class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><blockquote style="margin: 0 0 0 40px; border: none; padding: 0px;" class=""><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></div></blockquote><blockquote type="cite" class=""><div class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class=""><br class=""></div><div class="">This no longer looks symmetrical across the parameters. First parameter has label “with”, second doesn’t.</div></div></div></blockquote><div><br class=""></div><div><div>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.</div><div><br class=""></div><div>—CK</div><br class=""><blockquote type="cite" class=""><div class="" style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;"></div></blockquote></div><blockquote type="cite" class=""><div class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class="">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 class=""><br class=""></div><br class=""><div class="">
<div class="">— Radek</div>
</div>
<br class=""><div class=""><blockquote type="cite" class=""><div class="">On 09 Feb 2016, at 20:18, Dave Abrahams 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=""><div class=""><br 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.<br class=""><br class="">Here are some results for the importer; we're still tuning some of the<br class="">heuristics but overall we feel very good about the preposition<br class="">placement:<br class=""><br class=""> <a href="https://github.com/apple/swift-3-api-guidelines-review/commit/da7e512cf75688e6da148dd2a8b27ae9efcb8821?diff=split" class="">https://github.com/apple/swift-3-api-guidelines-review/commit/da7e512cf75688e6da148dd2a8b27ae9efcb8821?diff=split</a><br class=""><br class="">Note that this is not final wording, but here are the guidelines we're<br class="">working with for first argument labels:<br class=""><br class="">A. Try to form a grammatical phrase including the first argument and<br class=""> describing the primary semantics at the call site.<br class=""><br class="">B. The first argument gets a label when and only when:<br class=""><br class=""> 1. It does not form part of a grammatical phrase describing the<br class=""> primary semantics. For example,<br class=""> ```<br class=""> x.dismiss(animated: y)<br class=""> ```<br class=""> [more examples needed]<br class=""> Note that parameters with defaults never describe the primary<br class=""> semantics. so are always labeled.<br class=""> ```<br class=""> func invert(options options: SomeOptionSet = []) // yes<br class=""> func invert(_ options: SomeOptionSet = []) // no<br class=""> ```<br class=""><br class=""> 2. The method is a factory method; such calls should mirror<br class=""> initializers, with no preposition. For example,<br class=""> ```<br class=""> let x = UIColor(red: r, green: g, blue: b)<br class=""> let y = monitor.makeColor(red: r, green: g, blue: b)<br class=""> ```<br class=""><br class=""> 3. It is part of a prepositional phrase<br class=""><br class=""> a. The label normally starts with the preposition. <br class=""> For example, <br class=""> ```<br class=""> x.move(from: a, to: b)<br class=""> x.loadValues(forKeys: ["fox", "box", "lox"])<br class=""> ```<br class=""> b. ...unless the preposition would break a very tight association<br class=""> between parameters:<br class=""> ```<br class=""> x.moveTo(x: a, y: b)<br class=""> ```<br class=""> [encourage grouping parameters into higher-level concepts,<br class=""> e.g. Point, in these cases]<br class=""><br class=""><br class=""><br class="">Feedback most welcome, of course.<br class="">-- <br class="">-Dave<br class=""><br class="">_______________________________________________<br class="">swift-evolution mailing list<br class=""><a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a><br class=""><a href="https://lists.swift.org/mailman/listinfo/swift-evolution" class="">https://lists.swift.org/mailman/listinfo/swift-evolution</a><br class=""></div></div></blockquote></div><br class=""></div></div></div></div>_______________________________________________<br class="">swift-evolution mailing list<br class=""><a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a><br class="">https://lists.swift.org/mailman/listinfo/swift-evolution<br class=""></div></blockquote></div><br class=""></body></html>