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

[Dave Abrahams]

on Sat Jan 23 2016, Joe Groff <swift-evolution at swift.org> 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, 

Hi Joe, 

Like Doug, I disagree that we guide you into using prepositional phrases
for secondary arguments.  But I really want to address the "poor
variable names" part of what you said.  It's true, as far as it goes,
but one thing nobody knows is that there are a few more guidelines
planned that didn't make it out in time for the review.  One goes
something like this:

   Choose parameter names to serve your documentation comment. These
   names are not API, but they still matter.  Well-chosen names allow
   the summary to read smoothly and to fully-describe the API in just a
   few words.

The main audience for the argument label is the reader of the use-site,
while the main audience for the parameter name is the reader of the
documentation and declaration.  Therefore, they should often be
distinct, and whether an argument label makes a good parameter name is
mostly immaterial.

> 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
> }
>
> The shorthand thus doesn't save the good API citizen from much
> work. 

True!

> On the other hand, a developer who's unaware or uninterested in the
> guidelines and is just trying to C or Java in Swift gets argument
> labels by default that neither follow the guidelines nor meet their
> expectation:
>
> func atan2(y: Double, x: Double) -> Double { ... }
>
> atan2(10, 10) // Why doesn't this work?
> atan2(10, x: 10) // Nobody wants this
>
> And when staring down potentially dozens or hundreds of compile errors
> at various mismatched use sites, 

That apocalyptic-sounding scenario went by too fast for me to imagine
how it actually arises.  Care to spell that out?

> they're unlikely to reconsider their API naming choice, and will
> instead do the minimal amount of work to get their code to compile by
> suppressing the argument label. The language hasn't led this developer
> to better conventional API design either.
>
> I can think of a couple possible modifications to the language rule
> that could help reduce the surprise factor, and still lead people to
> good API design:

I'm all for having a discussion of different language rules, but let's
keep them in a separate thread, please!

-- 
-Dave