[swift-evolution] Some clarity lost from the great renaming

[Daniel Duan]

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 :)

> On Oct 18, 2016, at 6:43 PM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
> 
> 
> on Tue Oct 18 2016, Brandon Knope <swift-evolution at swift.org <mailto:swift-evolution at 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 at swift.org <mailto:swift-evolution at swift.org>
> https://lists.swift.org/mailman/listinfo/swift-evolution <https://lists.swift.org/mailman/listinfo/swift-evolution>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20161019/f1546d93/attachment.html>