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

[Dave Abrahams]

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

>> On Sat, Jan 23, 2016 at 12:00 AM, David Owens II via swift-evolution
>> <swift-evolution at swift.org
>> <mailto:swift-evolution at swift.org>>
>> wrote:
>>> Compensate For Weak Type Information as needed to clarify a parameter’s role.
>
>>> 
>>> Especially when a parameter type is NSObject, Any, AnyObject, or a
>>> fundamental type such Int or String, type information and context
>>> at the point of use may not fully convey intent. In this example,
>>> the declaration may be clear, but the use site is vague:
>>> 
>>> func add(observer: NSObject, for keyPath: String)
>>> grid.add(self, for: graphics) // vague
>>> 
>>> To restore clarity, precede each weakly-typed parameter with a noun describing its role:
>>> 
>>> func addObserver(_ observer: NSObject, forKeyPath path: String)
>>> grid.addObserver(self, forKeyPath: graphics) // clear
>> 
>
> 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.

FWIW, I agree with you that this one is awkward.  This seems like "all
parameters are peers that /can/ be usefully distinguished."

Putting "with" in the base name of the method makes me want to add
"and":

  connection.loginWithUsername(auth.name, andPassword: auth.password)

and I do not feel that the above has any advantages over:

  connection.login(username: auth.name, password: auth.password)

In fact, IMO the former seems to make "username" more important than
password, like there could be a different method that lets you login
with just a password and no username.

-- 
-Dave