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

[plx]

> On Jan 23, 2016, at 2:33 PM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
> 
> 
> on Sat Jan 23 2016, plx <swift-evolution at swift.org <mailto:swift-evolution at swift.org>> wrote:
> 
>>> On Jan 22, 2016, at 6:12 PM, Ross O'Brien via swift-evolution
>>> <swift-evolution at swift.org> wrote:
>>> 
>>> How would we apply this to delegate patterns?
>>> For example, would we keep
>>> tableview(tableView:cellForRowAtIndexPath:), or would we switch to
>>> delegate(tableView:cellForRowAtIndexPath:) ?
>>> Or perhaps better, for clarity over which protocol is being
>>> conformed to / which property of the delegator is calling the
>>> function:
>>> dataSource(tableView:cellForRowAtIndexPath:),
>>> delegate(tableView:didSelectRowAtIndexPath:)
>> 
>> FWIW, I am personally favorable to a more radical-renaming for delegate methods, roughly the below:
>> 
>> func numberOfSections(inTableView tableView: UITableView) -> Int // <- against guidelines, but symmetric
>> func numberOfRows(inTableView tableView: UITableView, forSection section: Int) -> Int
>> func cellForRow(inTableView tableView: UITableView, atIndexPath indexPath: NSIndexPath) -> UITableView
> 
> The interesting thing about delegate methods is that, for the most part,
> use-sites don't appear in user code.  So *if* you're going to come up with
> special conventions just for delegate methods you'd want to serve the
> declaration site.  I don't know what these things *ought* to look like,
> but the declarations above look to me like they've got an awful lot of
> redundancy that doesn't help readability.

Most of what follows should really be in the discussion about the Objective-C import, not here, but I’ll respond here with the parts relevant to the guidelines.

It seems self-evident that imported delegate methods violate the spirit of Swift’s API guidelines; in particular, the rule that “Methods can share a base name when they share the same basic meaning but operate on different types, or are in different domains” seems relevant. It’s thus been a bit surprising to me that delegate-style methods haven’t *already* gotten some special treatment; what I had isn’t great, but put it and some variants up against the original, like so:

func numberOfRows(in tableView: UITableView, forSection section: Int) -> Int
func numberOfRowsIn(tableView: UITableView, forSection section: Int) -> Int
func tableView(tableView: UITableView, numberOfRowsInSection section: Int) -> Int
func numberOfRows(inTableView tableView: UITableView, forSection section: Int) -> Int

…(note the longest is only ~10 characters longer than the shortest!). 

Although there might be an as-yet unseen option that’s superior to all of the above, just out of those 4 it’s hard to see how you can justify option #3 using the API guidelines; it also seems hard to envision a self-consistent expansion of the guidelines that’d lead to favoring #3.

As already noted this is really more-relevant to the “objective-c import revision”, but you can frame my points as obliquely asking “to what extent should the Swift API guidelines actually matter when doing the big Objective-C import?”

I also question your sense of real-world use of delegate protocols; just taking inventory of the most recent project I completed, it looks like it had 5 custom delegate-style protocols. Of these, 4 had exactly one implementation each, and 1 had exactly 2 implementations; I don’t think this is that untypical. If you accept it as not too atypical, it suggests a more uniform balance between defining a delegate protocol, using said protocol, and implementing said protocol.

To wind this digression down now, the API guidelines’ attitude towards redundancy seems somewhat troubling; no one wants needless redundancy, but natural languages tend towards redundancy (cf agreement/pleonasm/etc) and it’s not at all self-evident that less redundancy always implies increased readability (which you may or may not be intending to imply; I can’t tell)…especially when it’s easy to get fooled by increased speed-of-reading.

I will pick this discussion up in the Objective-C import review because I think it’s important.

> It's also worth asking whether the added complexity of special
> guidelines for delegates pays for itself.
> 
> 
> -- 
> -Dave
> 
> _______________________________________________
> 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/a918a0ea/attachment.html>