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

[Marc Knaup]

And I'd prefer logIn (verb) over login (noun) in the example :)

On Sat, Jan 23, 2016 at 12:07 PM, Thorsten Seitz via swift-evolution <
swift-evolution at swift.org> wrote:

>
> Am 23.01.2016 um 01:35 schrieb Erica Sadun via swift-evolution <
> swift-evolution at swift.org>:
>
>
> 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> 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)
>
>
> I would actually prefer one of
>
> func loginWithUsername(username: String, password: String)
> func login(withUsername username: String, password: String)
>
> because of the weak type information to just
>
> func login(sername: String, password: String)
>
>
> Of course the ideal version would define the types Username and Password
> (ideally with a future newtype construct :-) and then could use just
>
> func login(username: Username, password: Password)
>
>
> but
>
> addLineToPoint(p1: CGPoint, withThickness: CGFloat)
>
>
> Why should addLineTo(point: CGPoint, withThickness thickness: CGFloat) be
> considered as having weak type information for the point?
>
>
> -Thorsten
>
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160123/c1550fa0/attachment.html>