[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 12:48 PM, Jarod Long via swift-evolution
>> <swift-evolution at swift.org> wrote:
>> 
>> This is definitely more clear when you completely separate these
>> lines from their context, but code isn't written or read in complete
>> isolation like this, so I think these examples significantly
>> exaggerate the ambiguity of the pattern in the real world.
>> 
>> Even if you only make the minor change of renaming p to proximity
>> (which is really what it should be), the first example becomes
>> pretty clear:
>> 
>>> let next = current.updating(proximity)
>> 
>> 
>
> I just want to comment on this as I keep seeing this for arguments on
> the lists. APIs themselves should not be relying on well named inputs
> into them to create clear API signatures.


I don't think *anybody* on this list believes they should.

>
> 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.

> 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?

>> Ultimately, I don't think this is a very difficult pattern to
>> learn. Maybe the first handful of times you see it you'll need to
>> read the documentation to know exactly what it's doing, but once
>> you've seen it a few times, it's an instantly recognizable
>> pattern. If you see a gerund method, it returns a new thing by doing
>> the verb to the thing. Is it worth the redundancy and noise to save
>> new developers from possibly needing to look at a method's
>> documentation a few times?
>
> I really do not like the -ing form; it reads backwards. I intuitively
> expected the object of the “trimming” to be the parameters, not the
> instance invoking the method.
>
> let content = listItemView.text.trimmed(characters: .whitespaceAndNewlines)
>
> Whereas when I read the above, it’s natural to read that the "text is
> trimmed with” the parameter set. The former is, “the text is trimming
> with” the parameter set.

This is why you're supposed to first try the "ed" form.  The "ing" form
only comes into play (quoting the guidelines):

     When adding “ed” is not grammatical because the verb has a direct
     object

and in those cases, it reads forwards.

-- 
-Dave