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

[Dave Abrahams]

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

>> On Jan 22, 2016, at 5:26 PM, Michael Wells via swift-evolution
>> <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.
>
> Consider an exception rule:
>
> Prefer external names for the first parameter when the natural
> semantic relationship between the parameters is stronger than their
> relation to the operation. So
>
> login(username: String, password:String)
> moveTo(x: Double, y: Double)

used as

    login("dave", password: secret)
    moveTo(width, y: height)
?

I can't imagine you meant the latter one.

> but 
>
> addLineToPoint(p1: CGPoint, withThickness: CGFloat)

   addLineToPoint(origin, withThickness: CGFloat)

?

I don't see what salient information the word "Point" is adding here.

-- 
-Dave