Some clarity lost from the great renaming


(Brandon Knope) #1

I meant to bring this up a bit ago but just came across it again.

I find this to not read properly:

button.setTitle("Test", for: .normal) //for normal what?

The for argument is really only clear in meaning when you are typing it out and see that it is a UIControlState type. While reading it without this context is it as clear? .normal doesn't seem descriptive enough on its own.

Contrast this with UISegmentedControl:
segmented.dividerImage(forLeftSegmentState: .normal, rightSegmentState: .normal, barMetrics: .default)

Here the parameter labels are needed because there needs to be a distinction in the method between left and right. But here it is not forLeft: or forRight: it is the much more clear forLeftSegmentState:

So my question is: why was this not setTitle(forControlState:) or forButtonState, etc...?

Brandon

···

Sent from my iPad


(Dave Abrahams) #2

This is really not an evolution question at this point. I suggest
filing radars against UIKit for things whose names could be improved.

···

on Tue Oct 18 2016, Brandon Knope <swift-evolution@swift.org> wrote:

I meant to bring this up a bit ago but just came across it again.

I find this to not read properly:

button.setTitle("Test", for: .normal) //for normal what?

The for argument is really only clear in meaning when you are typing
it out and see that it is a UIControlState type. While reading it
without this context is it as clear? .normal doesn't seem descriptive
enough on its own.

Contrast this with UISegmentedControl:
segmented.dividerImage(forLeftSegmentState: .normal, rightSegmentState: .normal, barMetrics:
.default)

Here the parameter labels are needed because there needs to be a
distinction in the method between left and right. But here it is not
forLeft: or forRight: it is the much more clear forLeftSegmentState:

So my question is: why was this not setTitle(forControlState:) or forButtonState, etc...?

--
-Dave


(Hooman Mehr) #3

Is changing the mapping of Cocoa API considered a source breaking change or can we report such incidents as bugs if we think they don’t match API guidelines?

···

On Oct 18, 2016, at 6:43 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

on Tue Oct 18 2016, Brandon Knope <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

I meant to bring this up a bit ago but just came across it again.

I find this to not read properly:

button.setTitle("Test", for: .normal) //for normal what?

The for argument is really only clear in meaning when you are typing
it out and see that it is a UIControlState type. While reading it
without this context is it as clear? .normal doesn't seem descriptive
enough on its own.

Contrast this with UISegmentedControl:
segmented.dividerImage(forLeftSegmentState: .normal, rightSegmentState: .normal, barMetrics:
.default)

Here the parameter labels are needed because there needs to be a
distinction in the method between left and right. But here it is not
forLeft: or forRight: it is the much more clear forLeftSegmentState:

So my question is: why was this not setTitle(forControlState:) or forButtonState, etc...?

This is really not an evolution question at this point. I suggest
filing radars against UIKit for things whose names could be improved.

--
-Dave

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution


(Charles Srstka) #4

They can always add the new mapping, and leave the old one there but deprecate it.

Charles

···

On Oct 18, 2016, at 8:51 PM, Hooman Mehr via swift-evolution <swift-evolution@swift.org> wrote:

Is changing the mapping of Cocoa API considered a source breaking change or can we report such incidents as bugs if we think they don’t match API guidelines?

On Oct 18, 2016, at 6:43 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

on Tue Oct 18 2016, Brandon Knope <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

I meant to bring this up a bit ago but just came across it again.

I find this to not read properly:

button.setTitle("Test", for: .normal) //for normal what?

The for argument is really only clear in meaning when you are typing
it out and see that it is a UIControlState type. While reading it
without this context is it as clear? .normal doesn't seem descriptive
enough on its own.

Contrast this with UISegmentedControl:
segmented.dividerImage(forLeftSegmentState: .normal, rightSegmentState: .normal, barMetrics:
.default)

Here the parameter labels are needed because there needs to be a
distinction in the method between left and right. But here it is not
forLeft: or forRight: it is the much more clear forLeftSegmentState:

So my question is: why was this not setTitle(forControlState:) or forButtonState, etc...?

This is really not an evolution question at this point. I suggest
filing radars against UIKit for things whose names could be improved.

--
-Dave

_______________________________________________
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


(Dennis Lysenko) #5

I think if it's one example like in this instance then a compiler directive
to specify mapping if one does not already exist would be a more prudent
option than changing the entire mapping.

···

On Tue, Oct 18, 2016 at 9:51 PM Hooman Mehr via swift-evolution < swift-evolution@swift.org> wrote:

Is changing the mapping of Cocoa API considered a source breaking change
or can we report such incidents as bugs if we think they don’t match API
guidelines?

On Oct 18, 2016, at 6:43 PM, Dave Abrahams via swift-evolution < > swift-evolution@swift.org> wrote:

on Tue Oct 18 2016, Brandon Knope <swift-evolution@swift.org> wrote:

I meant to bring this up a bit ago but just came across it again.

I find this to not read properly:

button.setTitle("Test", for: .normal) //for normal what?

The for argument is really only clear in meaning when you are typing
it out and see that it is a UIControlState type. While reading it
without this context is it as clear? .normal doesn't seem descriptive
enough on its own.

Contrast this with UISegmentedControl:
segmented.dividerImage(forLeftSegmentState: .normal, rightSegmentState:
.normal, barMetrics:
.default)

Here the parameter labels are needed because there needs to be a
distinction in the method between left and right. But here it is not
forLeft: or forRight: it is the much more clear forLeftSegmentState:

So my question is: why was this not setTitle(forControlState:) or
forButtonState, etc...?

This is really not an evolution question at this point. I suggest
filing radars against UIKit for things whose names could be improved.

--
-Dave

_______________________________________________
swift-evolution mailing list
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


(Dave Abrahams) #6

Is changing the mapping of Cocoa API considered a source breaking
change or can we report such incidents as bugs if we think they don’t
match API guidelines?

You can report them as bugs even if it would be source breaking.

···

on Tue Oct 18 2016, Hooman Mehr <hooman-AT-mac.com> wrote:

On Oct 18, 2016, at 6:43 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

on Tue Oct 18 2016, Brandon Knope <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> > wrote:

I meant to bring this up a bit ago but just came across it again.

I find this to not read properly:

button.setTitle("Test", for: .normal) //for normal what?

The for argument is really only clear in meaning when you are typing
it out and see that it is a UIControlState type. While reading it
without this context is it as clear? .normal doesn't seem descriptive
enough on its own.

Contrast this with UISegmentedControl:
segmented.dividerImage(forLeftSegmentState: .normal, rightSegmentState: .normal, barMetrics:
.default)

Here the parameter labels are needed because there needs to be a
distinction in the method between left and right. But here it is not
forLeft: or forRight: it is the much more clear forLeftSegmentState:

So my question is: why was this not setTitle(forControlState:) or forButtonState, etc...?

This is really not an evolution question at this point. I suggest
filing radars against UIKit for things whose names could be improved.

--
-Dave

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

<https://lists.swift.org/mailman/listinfo/swift-evolution>

--
-Dave


(Brandon Knope) #7

Sorry! I was unsure if this would be a breaking change so thought I would seek feedback.

It sounds like I'm not the only one bothered by this so I will file a radar

Brandon

···

Sent from my iPad

On Oct 18, 2016, at 9:43 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

on Tue Oct 18 2016, Brandon Knope <swift-evolution@swift.org> wrote:

I meant to bring this up a bit ago but just came across it again.

I find this to not read properly:

button.setTitle("Test", for: .normal) //for normal what?

The for argument is really only clear in meaning when you are typing
it out and see that it is a UIControlState type. While reading it
without this context is it as clear? .normal doesn't seem descriptive
enough on its own.

Contrast this with UISegmentedControl:
segmented.dividerImage(forLeftSegmentState: .normal, rightSegmentState: .normal, barMetrics:
.default)

Here the parameter labels are needed because there needs to be a
distinction in the method between left and right. But here it is not
forLeft: or forRight: it is the much more clear forLeftSegmentState:

So my question is: why was this not setTitle(forControlState:) or forButtonState, etc...?

This is really not an evolution question at this point. I suggest
filing radars against UIKit for things whose names could be improved.

--
-Dave

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


(Daniel Duan) #8

I wrote a script to find “needless words” in our function names and made a similar discovery. If “doXWithY(_ y: Y)” gets renamed to “doX(with y: Y)” and Y happened to be a enum or have static members, at use site it become a little awkward. Following Brandon’s first example:

1. “normal” is an adjective, and preposition followed by adjective (“for normal”, “to default”, “with misc”) is ungrammatical. It’s very common to have enum cases being an adjective.
2. if the argument is a literal value (as opposed to a variable), the type information is not immediately obvious at use site. The function reads better if the enum type prefix is preserved: `botton.setTitle(“Test”, for: UIControlState.normal)`.

In these cases, we chose to preserve the words after the preposition to make the call site clearer.

These aren’t problems from the API Design Guideline. They should be considered carefully case by case. And yeah, not really something we can fix on this list :slight_smile:

···

On Oct 18, 2016, at 6:43 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

on Tue Oct 18 2016, Brandon Knope <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

I meant to bring this up a bit ago but just came across it again.

I find this to not read properly:

button.setTitle("Test", for: .normal) //for normal what?

The for argument is really only clear in meaning when you are typing
it out and see that it is a UIControlState type. While reading it
without this context is it as clear? .normal doesn't seem descriptive
enough on its own.

Contrast this with UISegmentedControl:
segmented.dividerImage(forLeftSegmentState: .normal, rightSegmentState: .normal, barMetrics:
.default)

Here the parameter labels are needed because there needs to be a
distinction in the method between left and right. But here it is not
forLeft: or forRight: it is the much more clear forLeftSegmentState:

So my question is: why was this not setTitle(forControlState:) or forButtonState, etc...?

This is really not an evolution question at this point. I suggest
filing radars against UIKit for things whose names could be improved.

--
-Dave

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution


(Dennis Lysenko) #9

Agree on this particular case being unintuitive. I've come across a number
of such cases in Swift 3 but never really put too much thought into them.
Maybe you could just use for: UIControlState.normal until a resolution for
this is found (if there is one).

···

On Tue, Oct 18, 2016 at 10:32 PM Dennis Lysenko <dennis.s.lysenko@gmail.com> wrote:

I think if it's one example like in this instance then a compiler
directive to specify mapping if one does not already exist would be a more
prudent option than changing the entire mapping.

On Tue, Oct 18, 2016 at 9:51 PM Hooman Mehr via swift-evolution < > swift-evolution@swift.org> wrote:

Is changing the mapping of Cocoa API considered a source breaking change
or can we report such incidents as bugs if we think they don’t match API
guidelines?

On Oct 18, 2016, at 6:43 PM, Dave Abrahams via swift-evolution < > swift-evolution@swift.org> wrote:

on Tue Oct 18 2016, Brandon Knope <swift-evolution@swift.org> wrote:

I meant to bring this up a bit ago but just came across it again.

I find this to not read properly:

button.setTitle("Test", for: .normal) //for normal what?

The for argument is really only clear in meaning when you are typing
it out and see that it is a UIControlState type. While reading it
without this context is it as clear? .normal doesn't seem descriptive
enough on its own.

Contrast this with UISegmentedControl:
segmented.dividerImage(forLeftSegmentState: .normal, rightSegmentState:
.normal, barMetrics:
.default)

Here the parameter labels are needed because there needs to be a
distinction in the method between left and right. But here it is not
forLeft: or forRight: it is the much more clear forLeftSegmentState:

So my question is: why was this not setTitle(forControlState:) or
forButtonState, etc...?

This is really not an evolution question at this point. I suggest
filing radars against UIKit for things whose names could be improved.

--
-Dave

_______________________________________________
swift-evolution mailing list
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