[swift-evolution] Issues with 0005-Better Translation of Objective-C APIs Into Swift
dabrahams at apple.com
Tue Feb 2 18:54:54 CST 2016
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.
> let content = listItemView.text.trimming(characters: .whitespaceAndNewlines)
> At least I have some context at the call site what the purpose of
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
>> 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
and in those cases, it reads forwards.
More information about the swift-evolution