<div dir="ltr">On Tue, Jun 21, 2016 at 6:44 PM, Darren Mo <span dir="ltr"><<a href="mailto:darren.mo@me.com" target="_blank">darren.mo@me.com</a>></span> wrote:<br><div class="gmail_extra"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div style="word-wrap:break-word"><span class="">On Jun 20, 2016, at 10:12 PM, Xiaodi Wu <<a href="mailto:xiaodi.wu@gmail.com" target="_blank">xiaodi.wu@gmail.com</a>> wrote:<br><div><blockquote type="cite"><div><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Mon, Jun 20, 2016 at 9:05 PM, Brent Royal-Gordon via swift-evolution <span dir="ltr"><<a href="mailto:swift-evolution@swift.org" target="_blank">swift-evolution@swift.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><span>> DispatchQueue.async(execute:) and DispatchQueue.sync(execute:)<br>
> --------------------------------------------------------------<br>
> The lack of verb in the base name bothers me. The API Design Guidelines say “methods with side-effects should read as imperative verb phrases”. You could argue that the argument label “execute” serves as the verb. However, .async and .sync are most commonly used with trailing closures where the argument label is not present.<br>
><br>
> This issue was brought up during the review, but I did not see it being addressed. Why not name the methods something like .executeAsync(_:) and .executeSync(_:)?<br>
<br>
</span>That feels a little redundant to me. It's worth remembering that the API Guidelines are a means of creating clear APIs, not an end in themselves. It's okay to deviate a little if you get a better result.<br></blockquote><div><br></div><div>The guideline that methods should "read as imperative verb phrases" applies to the full name, labels and arguments and all, and not just the base name. You'll recall that the original proposal had .asynchronously(execute:), which is very much an imperative phrase. `.async(execute:)` was substituted by popular demand, with "async" being regarded as a term-of-art exception.</div></div></div></div></div></blockquote><br></div></span><div>Can you link me something that says it applies to the full name?</div></div></blockquote><div><br></div><div>In the document, all examples for verb phrases and noun phrases include the labels and arguments (e.g.: "distance to y"). In the subsequent section, it outlines scenarios for labeling the first argument when it forms part of a prepositional phrase or other grammatical phrase; in either case, the label is read as part of the phrase. The only exception to this convention is explicitly outlined: "Initializer and factory method calls should form a phrase that does not include the first argument."</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div style="word-wrap:break-word"><div>In all the examples, the verb is always in the base name and the argument labels are always prepositions or objects (the grammar version).</div></div></blockquote><div><br></div><div>Yes; these names are exceptional in that way. But it is apt: the base name holds the distinguishing feature (async vs. sync), whereas the verb here is correctly a label for the argument, which is a code block to be executed.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div style="word-wrap:break-word"><div>And what about when a trailing closure is used? Then the verb disappears.</div></div></blockquote><div><br></div><div>Which is fine, because the verb couldn't really be anything else (`doNotExecute`?). To me, at least, braces surrounding code blocks satisfactorily imply 'do' or 'execute,' much like parentheses around arguments are sometimes taken to imply 'with' or 'using.'</div></div><br></div></div>