<div dir="ltr">Great points Erica.<div><br></div><div>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.</div><div><br></div><div>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.</div><div><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">On Sat, Feb 6, 2016 at 11:29 AM, Erica Sadun via swift-evolution <span dir="ltr"><<a href="mailto:swift-evolution@swift.org" target="_blank">swift-evolution@swift.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class=""><br>
> On Feb 5, 2016, at 2:32 PM, Dave Abrahams via swift-evolution <<a href="mailto:swift-evolution@swift.org">swift-evolution@swift.org</a>> wrote:<br>
><br>
><br>
> Given all the awesome feedback I've gotten on this thread, I went back<br>
> to the drawing board and came up with something new; I think this one<br>
> works. The previously-stated goals still apply:<br>
><br>
> * describe when and where to use argument labels<br>
> * require labels in many of the cases people have asked for them<br>
> * are understandable by humans (this means relatively simple)<br>
> * preserve important semantics communicated by existing APIs.<br>
><br>
> Please keep in mind that it is a non-goal to capture considerations we<br>
> think have a bearing on good names (such as relatedness of parameters):<br>
> it's to create simple guidelines that have the right effect in nearly<br>
> all cases.<br>
><br>
> A. When arguments can't be usefully distinguished from one another, none<br>
> should have argument labels, e.g. min(x,y), zip(x,y,z).<br>
<br>
</span>Personal bugaboo. Guidance should guide: Avoid argument labels when arguments cannot be usefully distinguished from one another.<br>
<span class=""><br>
><br>
> B. Otherwise,<br>
><br>
> 1. At the call site, a first parameter that has no argument label must<br>
> form part of a grammatical phrase that starts with the basename, less<br>
> any trailing nouns.<br>
><br>
> print(x)<br>
> a.contains(b)<br>
> a.mergeWith(b)<br>
> a.addGestureRecognizer(x)<br>
> ^~~~~~~~~~~~~~~~~ trailing noun<br>
><br>
> This phrase must have the correct semantic implications, so, e.g.<br>
><br>
> a.dismiss(b) // no, unless a is really dismissing b<br>
> a.dismissAnimated(b) // no, not grammatical<br>
> a.dismiss(animated: b) // yes, using a label<br>
<br>
</span>Skip parameter labels when the first argument completes a grammatically meaningful phrase starting with the base name (and apart from trailing nouns).<br>
<br>
> a.dismiss(b) // Not unless a is really dismissing some instance of b<br>
<span class=""><br>
<br>
<br>
><br>
> 2. If the first argument is part of a prepositional phrase, put the<br>
> parenthesis immediately after the preposition.<br>
><br>
> a.encodeWith(b)<br>
> a.moveFrom(b, to: c)<br>
><br>
> Thus, if words are required for any reason between the preposition<br>
> and the first argument, they go into the first argument label.<br>
><br>
> a.tracksWith(mediaType: b, composer: c)<br>
> a.moveTo(x: 22, y: 99)<br>
<br>
</span>When using prepositional phrases, use parentheses after the preposition. Place any supporting words into first argument labels.<br>
<br>
a.dismissUsing(animation: b)<br>
a.tracksOf(mediaType: b, composer: c)<br>
a.moveTo(x: 22, y: 99)<br>
<br>
<br>
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.<br>
<br>
a.colorWith(red: r, green: g, blue: b, alpha: a)<br>
<br>
I think this should probably be:<br>
<br>
a.color(red:, green:, blue:, alpha:)<br>
<span class=""><br>
><br>
> Notes:<br>
><br>
> a. I would recommend prepositions other than "with" in nearly all<br>
> cases, but that's not the point of these rules.<br>
<br>
</span>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.<br>
<span class=""><br>
> b. I can understand the aesthetic appeal of<br>
><br>
> a.move(from: b, to: c)<br>
><br>
> but I believe it is not a clear enough improvement to justify<br>
> additional complexity in the guidelines.<br>
<br>
</span>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:<br>
<br>
a.move(from: b, to: c)<br>
a.login(username: b, password: c)<br>
<br>
-- E, always attempting to be helpful, but understanding your frustration at getting this kind of feedback<br>
<div class="HOEnZb"><div class="h5"><br>
<br>
><br>
> Questions:<br>
><br>
> 1. I'm not expecting these guidelines to make everybody optimally happy,<br>
> all the time, but they shouldn't be harmful. Are there any cases for<br>
> which they produce results you couldn't live with?<br>
><br>
> 2. Are there any cases where you'd be confused about how to apply these<br>
> guidelines?<br>
><br>
> Thanks in advance for all your valuable input!<br>
><br>
> P.S. Doug is presently working on generating new importer results, based<br>
> on these guidelines, for your perusal. They should be ready soon.<br>
><br>
> --<br>
> -Dave<br>
><br>
> _______________________________________________<br>
> swift-evolution mailing list<br>
> <a href="mailto:swift-evolution@swift.org">swift-evolution@swift.org</a><br>
> <a href="https://lists.swift.org/mailman/listinfo/swift-evolution" rel="noreferrer" target="_blank">https://lists.swift.org/mailman/listinfo/swift-evolution</a><br>
<br>
_______________________________________________<br>
swift-evolution mailing list<br>
<a href="mailto:swift-evolution@swift.org">swift-evolution@swift.org</a><br>
<a href="https://lists.swift.org/mailman/listinfo/swift-evolution" rel="noreferrer" target="_blank">https://lists.swift.org/mailman/listinfo/swift-evolution</a><br>
</div></div></blockquote></div><br></div>