[swift-evolution] Delegate Method Conventions (was:[Review] SE-0023 API Design Guidelines)

[Dave Abrahams]

on Sat Jan 23 2016, plx <swift-evolution at swift.org> wrote:

>> 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. 

That's quite true.

> It’s thus been a bit surprising to me that delegate-style methods
> haven’t *already* gotten some special treatment; 

Well, it's a fact of life that major efforts like this one (probably
property behaviors are the same bucket) are going to have to land
without solving all the problems they are related to.  I believe
strongly that we should do *something* about delegate methods.  I also
believe they're a separable problem and we should be able to evaluate
the current direction without working out all the details of how we're
going to handle them.  That's why I changed the subject line: I'd like
to agree that special treatment for delegate methods in the importer is
out-of-scope in this review.

> 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

I assume you mean the 3rd one to be "the original?"

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

Sorry, I don't see why that is relevant.  Care to explain?

> 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.

You can't.

> 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?”

We're willing to accept that some imported APIs will not follow the
guidelines.

> 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; 

And how many use-sites were there?

> I don’t think this is that untypical. If you accept it as not too
> atypical,

I do.

> it suggests a more uniform balance between defining a delegate
> protocol, using said protocol, and implementing said protocol.

Not necessarily.  How many times did this project implement delegate
protocols that were defined elsewhere?  

In any case, for what it's worth, I personally think the direction
you're going with those delegate APIs is great, and it has the benefit
of bringing them into conformance with other guidelines.  My only point
in saying that the declaration site is more important with delegate
methods than with others is that there's more type information at the
declaration site of a method than at its use site, so there's definitely
no reason to make them more verbose than others.  Making them simply
follow the existing guidelines exactly is a simple solution that IMO
leads to good code, and one I would support.

However, what Cocoa guys like Tony Parker say about the eventual
direction of delegate APIs should probably carry a lot more weight than
what I say.

> 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.

This seems like a pretty vague concern.  Let's see concrete examples of
problems you think the guidelines' attitude toward redundancy will
cause.  FWIW, "omit needless words" isn't something we just came
up with ourselves: it's a time-honored principle of clear English
writing (google it).


-- 
-Dave