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

[Jordan Rose]

> On Jun 21, 2016, at 16:46, Darren Mo via swift-evolution <swift-evolution at swift.org> wrote:
> 
> On Jun 21, 2016, at 5:24 PM, Matt Wright <mww at apple.com <mailto:mww at apple.com>> wrote:
>>> On Jun 20, 2016, at 7:12 PM, Xiaodi Wu via swift-evolution <swift-evolution at swift.org <mailto:swift-evolution at swift.org>> wrote:
>>> On Mon, Jun 20, 2016 at 9:05 PM, Brent Royal-Gordon via swift-evolution <swift-evolution at swift.org <mailto: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.
>> 
>> Right, the naming here strayed from the guidelines here under the term-of-art exception. None of the various alternatives really fit amazingly well, the async{,hronous} part of the API name communicates an important facet of what the call does. In that it goes away and executes the closure “somewhere else”. I feel this particular point is lost in example such as perform{andWait}. `.asynchronously` was an attempt to move towards the guidelines but it still missed that mark. I believe it’s still clearer to have `.async` as an exception.
> 
> What do you think of the names .executeAsync/.executeSync or .asyncExecute/.syncExecute?

I honestly want these to stay light. I like perform/performAndWait fine, but executeAsync/asyncExecute seem overly verbose. They’re more English-like but don’t actually add any clarity, in that I think it’s really quite clear what the API does.

Jordan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160707/6d0ce48a/attachment.html>