[swift-evolution] [SE-0088] Dispatch API names
xiaodi.wu at gmail.com
Tue Jun 21 18:56:34 CDT 2016
On Tue, Jun 21, 2016 at 6:44 PM, Darren Mo <darren.mo at me.com> wrote:
> On Jun 20, 2016, at 10:12 PM, Xiaodi Wu <xiaodi.wu at gmail.com> wrote:
> On Mon, Jun 20, 2016 at 9:05 PM, Brent Royal-Gordon via swift-evolution <
> swift-evolution at swift.org> 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
>> 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.'
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the swift-evolution