<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">&lt;<a href="mailto:swift-evolution@swift.org" target="_blank">swift-evolution@swift.org</a>&gt;</span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><span class=""><br>
&gt; On Feb 5, 2016, at 2:32 PM, Dave Abrahams via swift-evolution &lt;<a href="mailto:swift-evolution@swift.org">swift-evolution@swift.org</a>&gt; wrote:<br>
&gt;<br>
&gt;<br>
&gt; Given all the awesome feedback I&#39;ve gotten on this thread, I went back<br>
&gt; to the drawing board and came up with something new; I think this one<br>
&gt; works.  The previously-stated goals still apply:<br>
&gt;<br>
&gt; * describe when and where to use argument labels<br>
&gt; * require labels in many of the cases people have asked for them<br>
&gt; * are understandable by humans (this means relatively simple)<br>
&gt; * preserve important semantics communicated by existing APIs.<br>
&gt;<br>
&gt; Please keep in mind that it is a non-goal to capture considerations we<br>
&gt; think have a bearing on good names (such as relatedness of parameters):<br>
&gt; it&#39;s to create simple guidelines that have the right effect in nearly<br>
&gt; all cases.<br>
&gt;<br>
&gt; A. When arguments can&#39;t be usefully distinguished from one another, none<br>
&gt;   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>
&gt;<br>
&gt; B. Otherwise,<br>
&gt;<br>
&gt;  1. At the call site, a first parameter that has no argument label must<br>
&gt;     form part of a grammatical phrase that starts with the basename, less<br>
&gt;     any trailing nouns.<br>
&gt;<br>
&gt;       print(x)<br>
&gt;       a.contains(b)<br>
&gt;       a.mergeWith(b)<br>
&gt;       a.addGestureRecognizer(x)<br>
&gt;            ^~~~~~~~~~~~~~~~~ trailing noun<br>
&gt;<br>
&gt;     This phrase must have the correct semantic implications, so, e.g.<br>
&gt;<br>
&gt;       a.dismiss(b)           // no, unless a is really dismissing b<br>
&gt;       a.dismissAnimated(b)   // no, not grammatical<br>
&gt;       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>
&gt;       a.dismiss(b)           // Not unless a is really dismissing some instance of b<br>
<span class=""><br>
<br>
<br>
&gt;<br>
&gt;  2. If the first argument is part of a prepositional phrase, put the<br>
&gt;     parenthesis immediately after the preposition.<br>
&gt;<br>
&gt;       a.encodeWith(b)<br>
&gt;       a.moveFrom(b, to: c)<br>
&gt;<br>
&gt;     Thus, if words are required for any reason between the preposition<br>
&gt;     and the first argument, they go into the first argument label.<br>
&gt;<br>
&gt;       a.tracksWith(mediaType: b, composer: c)<br>
&gt;       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 &quot;creating new instance rule&quot; and should probably be called out as such. I&#39;d like to see the &quot;if it works like an initializer it should be named with initializer label&quot; 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>
&gt;<br>
&gt; Notes:<br>
&gt;<br>
&gt; a. I would recommend prepositions other than &quot;with&quot; in nearly all<br>
&gt;   cases, but that&#39;s not the point of these rules.<br>
<br>
</span>When using &quot;with&quot; as your go-to preposition, carefully consider whether other more meaningful prepositions could apply. &quot;With&quot; tends to describe use at a call site rather than method or function semantics.<br>
<span class=""><br>
&gt; b. I can understand the aesthetic appeal of<br>
&gt;<br>
&gt;    a.move(from: b, to: c)<br>
&gt;<br>
&gt;   but I believe it is not a clear enough improvement to justify<br>
&gt;   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>
&gt;<br>
&gt; Questions:<br>
&gt;<br>
&gt; 1. I&#39;m not expecting these guidelines to make everybody optimally happy,<br>
&gt;   all the time, but they shouldn&#39;t be harmful.  Are there any cases for<br>
&gt;   which they produce results you couldn&#39;t live with?<br>
&gt;<br>
&gt; 2. Are there any cases where you&#39;d be confused about how to apply these<br>
&gt;   guidelines?<br>
&gt;<br>
&gt; Thanks in advance for all your valuable input!<br>
&gt;<br>
&gt; P.S. Doug is presently working on generating new importer results, based<br>
&gt;     on these guidelines, for your perusal.  They should be ready soon.<br>
&gt;<br>
&gt; --<br>
&gt; -Dave<br>
&gt;<br>
&gt; _______________________________________________<br>
&gt; swift-evolution mailing list<br>
&gt; <a href="mailto:swift-evolution@swift.org">swift-evolution@swift.org</a><br>
&gt; <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>