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

[Darren Mo via swift-evolution]

Should I create a bug report for changing `DispatchQueue.after` and 
`DispatchSource.read`?

Darren

> On Jun 21, 2016, at 7:35 PM, Darren Mo <darren...@me.com> wrote:
> 
> On Jun 21, 2016, at 5:28 PM, Matt Wright <m...@apple.com 
> <mailto:m...@apple.com>> wrote:
>>> On Jun 20, 2016, at 5:50 PM, Darren Mo via swift-evolution 
>>> <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:
>>> DispatchQueue.after(when:execute:)
>>> --
>>> This one simply doesn’t read grammatically. For example, `queue.after(when: 
>>> .now) { … }` becomes “queue, after when now …”. Since dispatch_after is 
>>> semantically just an extended version of dispatch_async (I think), we can 
>>> name this .executeAsync(after:_:).
>> 
>> I replied to messages out of order but I agree, moving `.after` onto .async 
>> seems like the more natural place for it to live.
> 
> Yay!
> 
>>> DispatchSource subclass names
>>> -
>>> Why is it DispatchSourceMemoryPressure instead of 
>>> MemoryPressureDispatchSource? I don’t think I’ve ever seen subclass names 
>>> where the superclass part is at the beginning of the name.
>> 
>> I’m not so keen to remove the Dispatch prefix from the front of the source 
>> types, given that we avoided doing that for the remainder of the module.
> 
> What is the rationale for keeping the Dispatch prefix anyways? (I couldn’t 
> find it in the archives.)
> 
>>> DispatchSource factory methods
>>> --
>>> e.g. DispatchSource.read(fileDescriptor:queue:). The API Design Guidelines 
>>> mandate that factory methods begin with the prefix “make”. Indeed, 
>>> DispatchSource.read might mislead people to think that a read will be 
>>> performed by this method. A better name would be 
>>> .makeReadSource(fileDescriptor:queue:).
>> 
>> Agreed, these should probably be brought into line with that guideline.
> 
> Yay!
> 
>>> And why are these factory methods on DispatchSource instead of initializers 
>>> on the subclasses? ReadDispatchSource.init(fileDescriptor:queue:) would be 
>>> way clearer.
>> 
>> The source types are not subclasses, due to implementation details they are 
>> protocols.
> 
> Oops, missed that. Sorry.

___
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

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

[Darren Mo via swift-evolution]

On Jun 21, 2016, at 5:24 PM, Matt Wright  wrote:
>> On Jun 20, 2016, at 7:12 PM, Xiaodi Wu via swift-evolution 
>>  wrote:
>> On Mon, Jun 20, 2016 at 9:05 PM, Brent Royal-Gordon via swift-evolution 
>>  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?___
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

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

[Darren Mo via swift-evolution]

On Jun 20, 2016, at 10:12 PM, Xiaodi Wu  wrote:
> On Mon, Jun 20, 2016 at 9:05 PM, Brent Royal-Gordon via swift-evolution 
> > 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 all the 
examples, the verb is always in the base name and the argument labels are 
always prepositions or objects (the grammar version).

And what about when a trailing closure is used? Then the verb disappears.___
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

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

[Darren Mo via swift-evolution]

On Jun 21, 2016, at 5:28 PM, Matt Wright <m...@apple.com> wrote:
>> On Jun 20, 2016, at 5:50 PM, Darren Mo via swift-evolution 
>> <swift-evolution@swift.org> wrote:
>> DispatchQueue.after(when:execute:)
>> --
>> This one simply doesn’t read grammatically. For example, `queue.after(when: 
>> .now) { … }` becomes “queue, after when now …”. Since dispatch_after is 
>> semantically just an extended version of dispatch_async (I think), we can 
>> name this .executeAsync(after:_:).
> 
> I replied to messages out of order but I agree, moving `.after` onto .async 
> seems like the more natural place for it to live.

Yay!

>> DispatchSource subclass names
>> -
>> Why is it DispatchSourceMemoryPressure instead of 
>> MemoryPressureDispatchSource? I don’t think I’ve ever seen subclass names 
>> where the superclass part is at the beginning of the name.
> 
> I’m not so keen to remove the Dispatch prefix from the front of the source 
> types, given that we avoided doing that for the remainder of the module.

What is the rationale for keeping the Dispatch prefix anyways? (I couldn’t find 
it in the archives.)

>> DispatchSource factory methods
>> --
>> e.g. DispatchSource.read(fileDescriptor:queue:). The API Design Guidelines 
>> mandate that factory methods begin with the prefix “make”. Indeed, 
>> DispatchSource.read might mislead people to think that a read will be 
>> performed by this method. A better name would be 
>> .makeReadSource(fileDescriptor:queue:).
> 
> Agreed, these should probably be brought into line with that guideline.

Yay!

>> And why are these factory methods on DispatchSource instead of initializers 
>> on the subclasses? ReadDispatchSource.init(fileDescriptor:queue:) would be 
>> way clearer.
> 
> The source types are not subclasses, due to implementation details they are 
> protocols.

Oops, missed that. Sorry.___
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

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

[Darren Mo via swift-evolution]

SE-0088 was accepted with revisions a month ago. However, some of the APIs just 
don’t feel right to me. I’ve only used DispatchQueue and DispatchSource so far, 
so I will only comment on those.

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(_:)?

DispatchQueue.after(when:execute:)
--
This one simply doesn’t read grammatically. For example, `queue.after(when: 
.now) { … }` becomes “queue, after when now …”. Since dispatch_after is 
semantically just an extended version of dispatch_async (I think), we can name 
this .executeAsync(after:_:).

DispatchSource subclass names
-
Why is it DispatchSourceMemoryPressure instead of MemoryPressureDispatchSource? 
I don’t think I’ve ever seen subclass names where the superclass part is at the 
beginning of the name.

DispatchSource factory methods
--
e.g. DispatchSource.read(fileDescriptor:queue:). The API Design Guidelines 
mandate that factory methods begin with the prefix “make”. Indeed, 
DispatchSource.read might mislead people to think that a read will be performed 
by this method. A better name would be .makeReadSource(fileDescriptor:queue:).

And why are these factory methods on DispatchSource instead of initializers on 
the subclasses? ReadDispatchSource.init(fileDescriptor:queue:) would be way 
clearer.___
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

Re: [swift-evolution] Add max/min to floating point types

[Darren Mo via swift-evolution]

> On Jun 12, 2016, at 11:35 PM, Stephen Canon  wrote:
> 
> 
>> On Jun 10, 2016, at 5:20 PM, Darren Mo > > wrote:
>> 
>>> – They’re not actually the maximum and minimum values of the type.  In 
>>> particular, that `max(Float.infinity, .max)` wouldn’t be `Float.max` is 
>>> pretty seriously confusing.
>> 
>> Infinity is a special value. I would argue that people who use infinity know 
>> exactly what they are doing and would not be thrown by Float.infinity being 
>> greater than Float.max. I am willing to bet that most regular users don’t 
>> even know that infinity can be represented since it is rarely needed in 
>> real-world usage.
> 
> For clarity, what use cases do you have in mind where the largest finite 
> value is more appropriate than infinity?

That… is a very good question.

My main use case was laying out fixed-width text. In the Objective-C days, I 
would use CGFLOAT_MAX. I guess when I started to write the same code in Swift, 
I didn’t stop to think about whether there was a better value. Now thanks to 
you, I see that CGFloat.infinity is the clearest and most appropriate value.

Proposal cancelled. Thanks! ☺️___
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

Re: [swift-evolution] Add max/min to floating point types

[Darren Mo via swift-evolution]

Thanks for the summary of the arguments against max/min! Comments inline.

> On Jun 10, 2016, at 6:51 PM, Stephen Canon <sca...@apple.com> wrote:
> 
> On Jun 10, 2016, at 12:38 PM, Xiaodi Wu via swift-evolution 
> <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:
> 
>> On Fri, Jun 10, 2016 at 1:24 PM, Darren Mo via swift-evolution 
>> <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:
>> Today, one can get max/min by doing:
>> 
>> let max = Float.greatestFiniteMagnitude
>> let min = -Float.greatestFiniteMagnitude
>> 
>> On review of the proposal for the new FloatingPoint, I too commented on the 
>> lack of `max` and `min`. You've pointed out the issue with infinity. But 
>> also, FLT_MIN (from your local friendly C universe and available in Swift, 
>> obviously) is actually the smallest representable positive value, so 
>> `Float.min` is of ambiguous meaning. It was therefore decided not to use 
>> those words `max` and `min`.
> 
> It’s worth noting that this issue has been pretty extensively discussed both 
> on- and off-list.  Although convenience is good, the objections to the 
> ambiguity of `.max` and `.min` would be *very* hard to overcome:
> 
> – They’re not actually the maximum and minimum values of the type.  In 
> particular, that `max(Float.infinity, .max)` wouldn’t be `Float.max` is 
> pretty seriously confusing.

Infinity is a special value. I would argue that people who use infinity know 
exactly what they are doing and would not be thrown by Float.infinity being 
greater than Float.max. I am willing to bet that most regular users don’t even 
know that infinity can be represented since it is rarely needed in real-world 
usage.

> 
> – The proposed `.min` doesn't align with the meaning of the "float-min-thing” 
> in most other major languages:
> 
>   In C, FLT_MIN is the smallest positive normal
>   In C++, std::numeric_limits::min() is the smallest positive 
> normal
>   In Python, sys.float_info.min is the smallest positive normal
>   In C#, .minValue is documented as “the smallest possible value”, but is 
> actually the value you want, rather than the documented –infinity.
>   In Java, MIN_VALUE is the smallest positive value (including subnormals)
>   In Ruby, MIN is the smallest positive normal
>   In R, double.xmin is the smallest positive normal
>   In MATLAB, realmin is the smallest positive normal
>   Actually, Rust is the only language I know of where `MIN` is the value 
> you want *and* correctly documented as such.
> 
> All that’s not to say that Swift can’t do this, but there’s a lot of 
> opportunity for confusion on this point, and having a very explicit name 
> isn’t really a bad thing.

I think if we have .min *and* .leastNormalMagnitude *and* 
.leastNonzeroMagnitude, then there is no ambiguity or confusion. Moreover, I 
would suspect most people naturally think of .min as the most-negative number 
that can be represented (c.f. the top search results for “FLT_MIN”). If this is 
true, then we have an opportunity to align the language with the user’s true 
desires instead of just following precedent.

> 
> – There is also some concern that having `.min` and `.max` with the same 
> names as on Integer types would lead people to try to use them the same way 
> in code, which generally isn’t going to work the way users expect.

What is an example of this?

> 
> – Steve

___
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

Re: [swift-evolution] Add max/min to floating point types

[Darren Mo via swift-evolution]

Interesting. I didn’t know that you couldn’t use CGFloat.max/CGFloat.min (aka 
CGFloat.greatestFiniteMagnitude/CGFloat.leastNormalMagnitude) with auto layout. 
Good to know.

However, I was not referring to auto layout, but to the calculation of text 
height based on a fixed width. Like:

let fixedWidthSize = CGSize(width: myWidth, height: 
CGFloat.greatestFiniteMagnitude)
let textHeight = myLabel.sizeThatFits(fixedWidthSize).height

I have done this many times before with no errors and I have seen other people 
do this too. (Surely you have as well!)

> On Jun 10, 2016, at 3:32 PM, Erica Sadun <er...@ericasadun.com> wrote:
> 
> CGFloat has .max and .min. And if you use them, you get:
> 2016-06-10 13:32:14.185 Untitled Page 10[18435:13174627] This 
> NSLayoutConstraint is being configured with a constant that exceeds internal 
> limits.  A smaller value will be substituted, but this problem should be 
> fixed. Break on void _NSLayoutConstraintNumberExceedsLimit() to debug.  This 
> will be logged only once.  This may break in the future.
> 
> -- E
> 
>> On Jun 10, 2016, at 12:24 PM, Darren Mo via swift-evolution 
>> <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:
>> 
>> Today, one can get max/min by doing:
>> 
>> let max = Float.greatestFiniteMagnitude
>> let min = -Float.greatestFiniteMagnitude
>> 
>> I propose that the floating point types expose properties for max/min.
>> 
>> max, in particular, is used quite a lot in UI code for fixed-width layout of 
>> text. But having to spell out greatestFiniteMagnitude every time is a pain. 
>> For example…
>> 
>> Compare this:
>> extension NSTextView {
>>func configureForFixedWidth() {
>>   minSize = NSSize.zero
>>   maxSize = NSSize(width: CGFloat.greatestFiniteMagnitude, height: 
>> CGFloat.greatestFiniteMagnitude)
>>   isHorizontallyResizable = false
>>   isVerticallyResizable = true
>> 
>>   textContainer?.containerSize = NSSize(width: bounds.width, height: 
>> CGFloat.greatestFiniteMagnitude)
>>   textContainer?.widthTracksTextView = true
>>}
>> }
>> 
>> To this:
>> extension NSTextView {
>>func configureForFixedWidth() {
>>   minSize = NSSize.zero
>>   maxSize = NSSize(width: CGFloat.max, height: CGFloat.max)
>>   isHorizontallyResizable = false
>>   isVerticallyResizable = true
> 
>> 
>>   textContainer?.containerSize = NSSize(width: bounds.width, height: 
>> CGFloat.max)
>>   textContainer?.widthTracksTextView = true
>>}
>> }
>> 
>> The latter snippet is much more understandable (and less typing). It is more 
>> understandable because users don’t have to know exactly how floating point 
>> works in order to get the equivalent of Int.max/Int.min for CGFloat.
>> 
>> One of the concerns with naming them max/min is that infinity/-infinity is 
>> technically the real max/min. We could name them finiteMax/finiteMin, but I 
>> think keeping the names consistent with Int et al. is important since they 
>> serve the same purpose. Besides, I think dealing with infinity is rare in 
>> real-world usage. Those that are using infinity know that it is obviously 
>> the true max.
>> 
>> I think adding these floating point properties is in line with Swift 3’s 
>> goals of consistency and refinement.
>> 
>> Thoughts?
>> ___
>> swift-evolution mailing list
>> swift-evolution@swift.org <mailto:swift-evolution@swift.org>
>> https://lists.swift.org/mailman/listinfo/swift-evolution
> 

___
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

[swift-evolution] Add max/min to floating point types

[Darren Mo via swift-evolution]

Today, one can get max/min by doing:

let max = Float.greatestFiniteMagnitude
let min = -Float.greatestFiniteMagnitude

I propose that the floating point types expose properties for max/min.

max, in particular, is used quite a lot in UI code for fixed-width layout of 
text. But having to spell out greatestFiniteMagnitude every time is a pain. For 
example…

Compare this:
extension NSTextView {
   func configureForFixedWidth() {
  minSize = NSSize.zero
  maxSize = NSSize(width: CGFloat.greatestFiniteMagnitude, height: 
CGFloat.greatestFiniteMagnitude)
  isHorizontallyResizable = false
  isVerticallyResizable = true

  textContainer?.containerSize = NSSize(width: bounds.width, height: 
CGFloat.greatestFiniteMagnitude)
  textContainer?.widthTracksTextView = true
   }
}

To this:
extension NSTextView {
   func configureForFixedWidth() {
  minSize = NSSize.zero
  maxSize = NSSize(width: CGFloat.max, height: CGFloat.max)
  isHorizontallyResizable = false
  isVerticallyResizable = true

  textContainer?.containerSize = NSSize(width: bounds.width, height: 
CGFloat.max)
  textContainer?.widthTracksTextView = true
   }
}

The latter snippet is much more understandable (and less typing). It is more 
understandable because users don’t have to know exactly how floating point 
works in order to get the equivalent of Int.max/Int.min for CGFloat.

One of the concerns with naming them max/min is that infinity/-infinity is 
technically the real max/min. We could name them finiteMax/finiteMin, but I 
think keeping the names consistent with Int et al. is important since they 
serve the same purpose. Besides, I think dealing with infinity is rare in 
real-world usage. Those that are using infinity know that it is obviously the 
true max.

I think adding these floating point properties is in line with Swift 3’s goals 
of consistency and refinement.

Thoughts?___
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

Re: [swift-evolution] [Review] SE-0088: Modernize libdispatch for Swift 3 naming conventions

[Darren Mo via swift-evolution]

Great, this is the libdispatch API that I’ve been dreaming about! I think it 
meshes well with the rest of Swift.

I am concerned about one thing though: the naming of the DispatchGroup methods 
synchronously/asynchronously.

They are hard to type correctly and ugly to look at.
sync/async are already well-established abbreviations in the tech industry.
They are adjectives without verbs, which goes against the API Design Guidelines.

I suggest sticking with the naming from the C API. For example:

let queue = …
queue.dispatchAsync {
  …
}

Cheers,
Darren

> Hello Swift community,
> 
> The review of "SE-0088: Modernize libdispatch for Swift 3 naming conventions" 
> begins now and runs through May 17. The proposal is available here:
> 
> https://github.com/apple/swift-evolution/blob/master/proposals/0088-libdispatch-for-swift3.md
> 
> Reviews are an important part of the Swift evolution process. All reviews 
> should be sent to the swift-evolution mailing list at
> 
> https://lists.swift.org/mailman/listinfo/swift-evolution
> 
> or, if you would like to keep your feedback private, directly to the review 
> manager.
> 
> What goes into a review?
> 
> The goal of the review process is to improve the proposal under review 
> through constructive criticism and contribute to the direction of Swift. When 
> writing your review, here are some questions you might want to answer in your 
> review:
> 
> * What is your evaluation of the proposal?
> * Is the problem being addressed significant enough to warrant a change to 
> Swift?
> * Does this proposal fit well with the feel and direction of Swift?
> * If you have used other languages or libraries with a similar feature, how 
> do you feel that this proposal compares to those?
> * How much effort did you put into your review? A glance, a quick reading, or 
> an in-depth study?
> 
> More information about the Swift evolution process is available at
> 
> https://github.com/apple/swift-evolution/blob/master/process.md
> 
> Thank you,
> 
> -Chris Lattner
> Review Manager
> 
> 
> ___
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

Re: [swift-evolution] [review] SE-0088: Modernize libdispatch for Swift 3 naming conventions

[Darren Mo via swift-evolution]

Great, this is the libdispatch API that I’ve been dreaming about! I think it 
meshes well with the rest of Swift.

I am concerned about one thing though: the naming of the DispatchGroup methods 
synchronously/asynchronously.

1. They are hard to type correctly and ugly to look at.
2. sync/async are already well-established abbreviations in the tech industry.
3. They are adjectives without verbs, which goes against the API Design 
Guidelines.

I suggest sticking with the naming from the C API. For example:

let queue = …
queue.dispatchAsync {
   …
}
___
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution