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

[Douglas Gregor]

> On Jan 22, 2016, at 4:35 PM, Erica Sadun via swift-evolution <swift-evolution at swift.org> wrote:
> 
>> 
>> On Jan 22, 2016, at 5:26 PM, Michael Wells via swift-evolution <swift-evolution at swift.org <mailto: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)

I’ve tried to capture a similar rule before without much luck: to me, it’s something about the various parameters being equally suited to being the direct object of the verb in the base name. I can

	loginWithPassword(String, username: String)

or

	loginWithUsername(String, password: String)

and it’s only convention that gives slight preference to the latter: username and password are both equally important parameters to the “login” operation, so it feels wrong to have to give one of them the extra weight of being described in the base name.

	transition(from from: UIViewController, to: UIViewController, etc.)

is one of my favorite examples where the first two parameters have equal importance.

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

As noted elsewhere, this isn’t a good counterexample, because “Point” is needless:

	addLineTo(p1: CGPoint, withThickness: CGFloat)

(the “with” also seems unnecessary to me). 

However, the previously-shown

	func addObserver(observer: NSObject, forKeyPath path: String)

has a first parameter that is far more important than the second parameter, and the base name (“add”) is fairly generic on its own.

	- Doug

> -- Erica
> 
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org <mailto:swift-evolution at swift.org>
> https://lists.swift.org/mailman/listinfo/swift-evolution <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/71482454/attachment-0001.html>