On Tue, Jun 21, 2016 at 6:44 PM, Darren Mo <[email protected]> wrote: > On Jun 20, 2016, at 10:12 PM, Xiaodi Wu <[email protected]> wrote: > > On Mon, Jun 20, 2016 at 9:05 PM, Brent Royal-Gordon via swift-evolution < > [email protected]> wrote: > >> > DispatchQueue.async(execute:) and DispatchQueue.sync(execute:) >> > -------------------------------------------------------------- >> > 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. >> > >> > 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(_:)? >> >> 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. >> > > 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. > > > Can you link me something that says it applies to the full name? >
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." > In all the examples, the verb is always in the base name and the argument > labels are always prepositions or objects (the grammar version). > 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. > And what about when a trailing closure is used? Then the verb disappears. > 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.'
_______________________________________________ swift-evolution mailing list [email protected] https://lists.swift.org/mailman/listinfo/swift-evolution
