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

[Dave Abrahams]

on Fri Jan 22 2016, Rob Mayoff <swift-evolution at swift.org> wrote:

>>
>> Where this rule feels clumsy to me is in code such as
>>
>> func loginWithUsername(username: String, password: String) -> Bool
>>
>> vs.
>>
>> func login(username: String, password: String) -> Bool
>>
>> But maybe it just takes some time to get used to the style.
>>
>
> You're right that loginWithUsername is clumsy, since the first argument is
> probably an expression like "username" or "usernameField.text" or somesuch.
> But I would much prefer
>
>     func loginAs(username: String, password: String) -> Bool
>
> because it reads like something I'd actually say. Consider telling a
> coworker "log in as 'mayoff', password 'bikeshed'".

  loginAs("mayoff", password: secret)

[Note that writing out the use-site is crucial for evaluating the
effects of these guidelines.  Declarations are not as important]

Great point.  One of the things that kept happening when we were
bikeshedding these guidelines was that in many cases where we thought an
exception (i.e. complication) in the rules was needed to handle some
special case, there was a way of solving the problem within the
(simpler) rules if you just spent a little longer thinking about it.

Here's another wrinkle: to make it sound like something you'd say,
though, wouldn't you want "withPassword?"

So the question is, which leads to better use-sites?

  loginAs("mayoff", withPassword: secret)

  login(username: "mayoff", password: secret)

? I think the former wins.

-- 
-Dave