[swift-evolution] [SE-0088] Dispatch API names

[Xiaodi Wu]

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
>> .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.'
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160621/bd81c0ce/attachment.html>