[swift-evolution] Issues with 0005-Better Translation of Objective-C APIs Into Swift

[Dave Abrahams]

on Tue Feb 02 2016, David Owens II <swift-evolution at swift.org> wrote:

>> On Feb 2, 2016, at 4:54 PM, Dave Abrahams via swift-evolution
>> <swift-evolution at swift.org> wrote:
>> 
>>> The following version of the API is significantly more clear with no
>>> requirement of the variable names to be matched to the expectations of
>
>>> the API signature:
>>> 
>>> let next = current.updating(proximity: p)
>> 
>> Either of these, IMO, clarify that API much better:
>> 
>>  let next = current.replacingProximityWith(p)
>>  let next = current.settingProximityTo(p)
>> 
>> but so what?  The example started with a poor API; there are any number
>> of things one could do to improve it.
>
> The point was to highlight that the clarity should be coming from the
> API, not the inputs to the API.

I don't think anyone disagrees with that. I do think if you imagine that
the inputs to the method are actively misleading you can make its name
arbitrarily complex in order to counteract that, which would ultimately
hurt the readability of real code that generally isn't maliciously
named.

>>> Similarly,
>>> 
>>> let content = listItemView.text.trimming(characters: .whitespaceAndNewlines)
>>> 
>>> At least I have some context at the call site what the purpose of
>>> .whitespaceAndNewlines.
>> 
>> You wouldn't say "go to the garden and trim the plant: rhododendrons".
>> It isn't necessary for comprehension.  Why do you feel characters: is
>> necessary here?
>
> Because unlike the English phrase, "trimming" does not have an
> implicit object set based on the context of a string; what else would
> you typically trim in a garden other than plant life? 

What else would you trim from a string than characters?  I don't get the
difference.

> I could naturally create an API that allows trimming by a line range
> or string content, as an example.
>
> "public func foo() {}".trimmed(text: "public ")
> longContentWithKnownPreamble.trimmed(lines: 0..<5)
>
> We could make these different APIs as opposed to overloads, though I'm
> not convinced that they are not simply different ways to trim content.

I'm sure they *are* different ways to trim content.

I can't understand using "trimmed" the way you have above; it seems to
actively fight with the English language and does not strike me as clear.

-- 
-Dave