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

[Dave Abrahams]

on Wed Feb 03 2016, Gwendal Roué <gwendal.roue-AT-gmail.com> wrote:

>>>> 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?
>>> 
>>> Precisely because of what you stated a few lines above : "I don't
>
>>> think *anybody* on this list believes [API] should [be relying on well
>>> named inputs »:
>>> 
>>> 	let s: NSCharacterSet = .whitespaceAndNewlines
>>> 	let content = listItemView.text.trimming(s)	// what?
>> 
>> That's not relying on well named inputs; it's relying on context, and
>> *that* is perfectly alright.  We are never going to get to the point
>> that you can do without context in reading code.  Proof: there's no
>> label for the receiver, yet you're not complaining.  is
>> 
>>      v.text.trimming(characters: s)
>> 
>> somehow perfectly clear when
>> 
>>      listItemView.text.trimming(s)
>> 
>> is not?
>
> Well, Dave, despite all your efforts to make points, one version
> requires more context than the other, and is thus less clear.
> You are in the brevity team, that’s pretty clear. 

No, really, I'm in the clarity team.  The same rules that go for English
go here.  Clarify what's ambiguous, or that you can't easily get from
context.  Clarifying things that are readily available from context just
makes code/prose/whatever *less* clear.

It is true that you can't know what context an API will be used in.
Does that mean you should preemptively build in as many clarifications
as possible in case the context leaves usage unclear?  IMO, no.  If each
of our words came pre-loaded with clarification, it would make ordinary
sentences unmanageable.  

The author of an API cannot guarantee clarity at the use-site.  The best
she can do is to provide the user of the API with the tools needed to
make use-sites clear.  But part of that is a responsibility not to force
detail into the use-site that isn't going to be helpful in most cases.

-- 
-Dave