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

[Joe Groff]

> On Jan 23, 2016, at 11:10 PM, Douglas Gregor <dgregor at apple.com> wrote:
> 
>> 
>> On Jan 23, 2016, at 10:45 AM, Joe Groff <jgroff at apple.com <mailto:jgroff at apple.com>> wrote:
>> 
>> This all looks good to me (aside from the linguistic problems with verb conjugation I've raised in another subthread). However, I think these naming guidelines lead us to reconsider our default argument labeling rules for 'func' declarations again, as David Owens and others have suggested. The stated goal of the current language rule is to guide people into good API design following our conventions, but I don't think it succeeds in serving that purpose. If you follow the guidelines, the argument labels for your secondary arguments generally end up becoming prepositional phrases, which make for poor variable names, and you're naturally guided to giving the argument an explicit descriptive binding name:
>> 
>> func perform(stuff: Stuff, with: Thing) {
>>   with.apply(stuff) // 'with' is a weird variable name
>> }
>> 
>> func perform(stuff: Stuff, with thing: Thing) {
>>   thing.apply(stuff) // 'thing' is better
>> }
> 
> I don’t understand how you came to the conclusion that secondary arguments generally end up becoming prepositional phrases.

This might be Cocoa bias leaking through, but nearly every example in the proposal that has secondary labeled arguments uses a prepositional phrase for them, aside from special cases like defaulted arguments. Prepositional phrases also fall naturally from the "be grammatical" and "clarity at the point of use" admonitions. If you don't think this is representative of your intent, then you might need to make the showcased examples more diverse.

-Joe
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160125/a12fd777/attachment.html>