[swift-evolution] When to use argument labels, part DEUX (was: when to use argument labels (a new approach))

[Andrew Bennett]

Great points Erica.

I just wanted to chip in and say thanks to everyone participating.
Discussing it thoroughly is important, whether the individual discussions
result in changes to the proposal or not. Finding a clear, well reasoned
and thoroughly discussed guidelines will have a massive benefit to Swift.

The benefit of clear API guidelines on code quality is likely to have a
further reaching and longer lasting effect than even many of the more
concrete proposals to clean up syntax and improve the type system.


On Sat, Feb 6, 2016 at 11:29 AM, Erica Sadun via swift-evolution <
swift-evolution at swift.org> wrote:

>
> > On Feb 5, 2016, at 2:32 PM, Dave Abrahams via swift-evolution <
> swift-evolution at swift.org> wrote:
> >
> >
> > Given all the awesome feedback I've gotten on this thread, I went back
> > to the drawing board and came up with something new; I think this one
> > works.  The previously-stated goals still apply:
> >
> > * describe when and where to use argument labels
> > * require labels in many of the cases people have asked for them
> > * are understandable by humans (this means relatively simple)
> > * preserve important semantics communicated by existing APIs.
> >
> > Please keep in mind that it is a non-goal to capture considerations we
> > think have a bearing on good names (such as relatedness of parameters):
> > it's to create simple guidelines that have the right effect in nearly
> > all cases.
> >
> > A. When arguments can't be usefully distinguished from one another, none
> >   should have argument labels, e.g. min(x,y), zip(x,y,z).
>
> Personal bugaboo. Guidance should guide: Avoid argument labels when
> arguments cannot be usefully distinguished from one another.
>
> >
> > B. Otherwise,
> >
> >  1. At the call site, a first parameter that has no argument label must
> >     form part of a grammatical phrase that starts with the basename, less
> >     any trailing nouns.
> >
> >       print(x)
> >       a.contains(b)
> >       a.mergeWith(b)
> >       a.addGestureRecognizer(x)
> >            ^~~~~~~~~~~~~~~~~ trailing noun
> >
> >     This phrase must have the correct semantic implications, so, e.g.
> >
> >       a.dismiss(b)           // no, unless a is really dismissing b
> >       a.dismissAnimated(b)   // no, not grammatical
> >       a.dismiss(animated: b) // yes, using a label
>
> Skip parameter labels when the first argument completes a grammatically
> meaningful phrase starting with the base name (and apart from trailing
> nouns).
>
> >       a.dismiss(b)           // Not unless a is really dismissing some
> instance of b
>
>
>
> >
> >  2. If the first argument is part of a prepositional phrase, put the
> >     parenthesis immediately after the preposition.
> >
> >       a.encodeWith(b)
> >       a.moveFrom(b, to: c)
> >
> >     Thus, if words are required for any reason between the preposition
> >     and the first argument, they go into the first argument label.
> >
> >       a.tracksWith(mediaType: b, composer: c)
> >       a.moveTo(x: 22, y: 99)
>
> When using prepositional phrases, use parentheses after the preposition.
> Place any supporting words into first argument labels.
>
> a.dismissUsing(animation: b)
> a.tracksOf(mediaType: b, composer: c)
> a.moveTo(x: 22, y: 99)
>
>
> AGAINST: this worked better with your "creating new instance rule" and
> should probably be called out as such. I'd like to see the "if it works
> like an initializer it should be named with initializer label" bits come
> back.
>
> a.colorWith(red: r, green: g, blue: b, alpha: a)
>
> I think this should probably be:
>
> a.color(red:, green:, blue:, alpha:)
>
> >
> > Notes:
> >
> > a. I would recommend prepositions other than "with" in nearly all
> >   cases, but that's not the point of these rules.
>
> When using "with" as your go-to preposition, carefully consider whether
> other more meaningful prepositions could apply. "With" tends to describe
> use at a call site rather than method or function semantics.
>
> > b. I can understand the aesthetic appeal of
> >
> >    a.move(from: b, to: c)
> >
> >   but I believe it is not a clear enough improvement to justify
> >   additional complexity in the guidelines.
>
> When the natural semantic relationship between the arguments  is stronger
> than the relationship between the method name and the first argument, use
> first argument labels, whether the label is a noun or a preposition:
>
> a.move(from: b, to: c)
> a.login(username: b, password: c)
>
> -- E, always attempting to be helpful, but understanding your frustration
> at getting this kind of feedback
>
>
> >
> > Questions:
> >
> > 1. I'm not expecting these guidelines to make everybody optimally happy,
> >   all the time, but they shouldn't be harmful.  Are there any cases for
> >   which they produce results you couldn't live with?
> >
> > 2. Are there any cases where you'd be confused about how to apply these
> >   guidelines?
> >
> > Thanks in advance for all your valuable input!
> >
> > P.S. Doug is presently working on generating new importer results, based
> >     on these guidelines, for your perusal.  They should be ready soon.
> >
> > --
> > -Dave
> >
> > _______________________________________________
> > swift-evolution mailing list
> > swift-evolution at swift.org
> > https://lists.swift.org/mailman/listinfo/swift-evolution
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160206/4b6f0c81/attachment.html>