[swift-evolution] [Review] SE-0023 API Design Guidelines

[Paul Cantrell]

> On Jan 24, 2016, at 11:49 PM, Dave Abrahams <dabrahams at apple.com> wrote:
> 
> on Sun Jan 24 2016, Paul Cantrell <cantrell-AT-pobox.com> wrote:
> 
>> You may have hit on an underlying principle with your “direct object
>> of the method” observation: many of the cases we’re talking about
>> where the first arg wants a label are ones where the method is a verb
>> and its direct object is not the first arg alone, either because (1)
>> the direct object is something other than the first arg, (2) the
>> direct object is several args taken together, or (3) the verb is not
>> transitive.
>> 
>> Could that lead to an improvement in the guidelines?
> 
> I think it's very promising; we'll have to see how well it flies.
> 
>> Case (1) covers the trailing closure above, and also typedContent
>> below, whose direct object is implicit. Case (2) covers moveTo(x:y:)
>> and arguably also covers logInWith(username:password:). (Aside:
>> “login” is a noun and “log in” is a verb, dang it, and the method
>> should be “logIn” … but we never do that because it looks
>> ridiculous. Grammar…!) Case (3) covers dismissAnimated.
> 
> Nice!

In the search for the better guideline that eases the widespread concerns about the “first arg” rule, it seems like there are several promising options:

1. Erica & Radek’s razor that a word should move to the first arg label if its meaning is more tightly coupled to the argument than to the method as a whole.

2. The related razor that a word should move to the first arg label if it would create the misleading impression of an association with words from the method name (e.g. “resourceWithPathFragment” when _all_ resources have absolute URLs, and it’s the arg that is a path fragment).

3. My notion above that it might have to do with whether the first arg along is the direct object of the method name.

4. A more open-ended loosening of the guidelines that leaves a little more room for judgement, which might be as simple as replacing the phrase “There are only a few exceptions” with “Common exceptions include” in the guidelines.

I’d loosely prefer those options in that order, but all seem plausible to me.


>>>>   service.resource("/foo")
>>>>   service.resource(absoluteURL: "http://bar.com")
>>>>   service.resource(absoluteURL: NSURL(string: "http://bar.com"))
>>> 
>>> Sorry, perhaps it should be obvious, but why do you need the label at
>>> all here?  Seems to me you could do this with two overloads, since it's
>>> easy to detect when a string is an absolute URL.
>> 
>> An excellent question, and I’ll try to answer it without going too far
>> off topic:
>> 
>> It’s a security feature. Because of how the first flavor (path
>> fragment) works, it’s likely that unsanitized user input will creep
>> into it, e.g. "/user/\(userTextField.text)". (This is doubly true of
>> its counterpart resource.child(…).) Auto-detecting absolute URLs would
>> be dangerous: it could cause problems such as leaking credentials or
>> posting sensitive data to a malicious server. The flavor that takes
>> absolute URLs, on the other hand, is typically traversing intra-API
>> hrefs returned by the API itself. I wanted to keep those use cases
>> well separated.
> 
> I'll take your word for it; it definitely sounds like you know what
> you're doing in this area.

Well, I’ve thought hard about it … though that’s hardly the same thing!


>> Consistency is always in tension with expressivity, and it’s a hard
>> balance to strike.
>> 
>> The problem for those of us outside Apple is not that we’re bound by
>> the guidelines; it’s that we aren’t. If the guidelines get in the way
>> too much, people will just ignore them, and they’ll lose their
>> value. If they’re too loose, they lose their value. It’s a tricky
>> middle ground.
> 
> Don't worry, we're aware of these risks.  We want these guidelines to be
> widely adopted outside Apple and lead to more overall uniformity in how
> Swift code is written: that's good for everybody concerned.  If they
> aren't acceptable to our customers, we'll have failed.

I meant that not so much as a worry as a statement of appreciation for your dilemma. As with all these questions, my inclination is to dump as much opinion and useful info as I can, then trust the core team to digest it all and make a wise decision. “Discussion by committee, design by small group” is a good model.

Cheers,

Paul