<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Mon, Feb 8, 2016 at 12:45 AM, Dave Abrahams 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:0px 0px 0px 0.8ex;padding-left:1ex;border-left-color:rgb(204,204,204);border-left-width:1px;border-left-style:solid"><span><br>
on Sun Feb 07 2016, Matthew Judge &lt;<a href="mailto:swift-evolution@swift.org">swift-evolution@swift.org</a>&gt; wrote:<br>
<br>
</span><span>&gt; I think part of where the current guidelines struggle is the ambiguity<br>
&gt; of the term &quot;argument label&quot;<br>
<br>
</span>There&#39;s nothing ambiguous about it; it&#39;s the thing you write, with a<br>
trailing colon, before an argument in an argument list.<br>
<span><br>
&gt; so just for the sake of discussion I&#39;m going to define terms to be<br>
&gt; explicit (not saying these are precisely the right terms).<br>
&gt;<br>
&gt; - External parameter names: names used to refer to parameters at the<br>
&gt; use site<br>
<br>
</span>But they don&#39;t refer to parameters; they introduce arguments.<br>
<br>
     moveFrom(x, to: y)<br>
<br>
“to” introduces an argument. That&#39;s why we&#39;re calling them argument<br>
labels.<br></blockquote><div><br></div><div>Agreed - I was just trying to distinguish between the two concepts.</div><div><br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;padding-left:1ex;border-left-color:rgb(204,204,204);border-left-width:1px;border-left-style:solid"><span><br>
&gt; a.moveTo(x: 1, y: 2) // external parameter names are &quot;x&quot; and &quot;y&quot;<br>
&gt; a.addGestureRecognizer(b) // does not have an external parameter name<br>
&gt;<br>
&gt; - Argument labels: words used to describe the argument being passed in<br>
&gt; a.moveTo(x: 1, y: 2) // argument labels are &quot;x&quot; and &quot;y&quot;<br>
&gt; a.addGestureRecognizer(b) // argument label is &quot;GestureRecognizer&quot;<br>
<br>
</span>Now you&#39;re redefining “argument label.”  Why?<br></blockquote><div><br></div><div><br>I don&#39;t so much want to redefine &quot;argument label&quot; as have a term to describe this concept.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;padding-left:1ex;border-left-color:rgb(204,204,204);border-left-width:1px;border-left-style:solid">
<span><br>
&gt; Both of these are referred to as &quot;argument labels&quot; in the guidelines<br>
<br>
</span>Not unless I made a big mistake.  It is only supposed to mean what you<br>
are calling an “external parameter name.”<br></blockquote><div><br></div><div>I was reading this part of B.2: &quot;first argument is part of a prepositional phrase, put the parenthesis immediately after the preposition.&quot; as &quot;move the preposition from the first argument label into the base name&quot; but you&#39;re right, your language doesn&#39;t actually imply that the preposition is part of the argument label. My apologies.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;padding-left:1ex;border-left-color:rgb(204,204,204);border-left-width:1px;border-left-style:solid">
<span><br>
&gt; and most of the discussion, but they are slightly different (though<br>
&gt; overlapping) things. For instance, B.1 refers to &quot;external parameter<br>
&gt; names&quot; and B.2 refers to &quot;argument labels&quot;<br>
<br>
</span>I think you&#39;ve misread the language there.  Would you mind re-evaluating<br>
the rest of what you&#39;re saying here in that light?  I think we need to<br>
start from a common understanding.<br></blockquote><div><br></div><div>The key point from the rest of what I&#39;m saying is that the guideline for when to omit words in a method/function name can be more consistently and clearly applied to my redefinition of &quot;argument label&quot;... The reason we keep &quot;gestureRecognizer&quot; is the same regardless of whether it is spelled:<br> a.add(gestureRecognizer: b)<br> a.addGestureRecognizer(b)</div><div> and the reason we omit the argument label (original definition) in the following are different.<br> anArray.add(b) // Prune &quot;Element&quot; w/o changing semantic meaning<br> a.addGestureRecognizer(b) // Words describing the first argument are already in the base name</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;padding-left:1ex;border-left-color:rgb(204,204,204);border-left-width:1px;border-left-style:solid">
<div><div class="h5"><br>
<br>
&gt; I think my distinction between these terms makes the guidelines simpler with fewer caveats:<br>
&gt;<br>
&gt; 1. Prune needless and redundant words from the argument labels<br>
&gt; (i.e. remove any word that can be removed without confusing the<br>
&gt; semantic intent)<br>
&gt; 2. If the method reads as part of a grammatical phrase, prefer to<br>
&gt; locate the first argument label as part of the base name instead of as<br>
&gt; an external parameter name.<br>
&gt; Special Cases/Exceptions:<br>
&gt; a. Arguments with a default value should use an external parameter name<br>
&gt; b. Arguments with similar semantic importance should be treated the<br>
&gt; same (use external parameter names for argument labels or don&#39;t label<br>
&gt; any)<br>
&gt;<br>
&gt; Not saying these are right/perfect, but I do think the distinction of<br>
&gt; guidelines for argument labels and external parameter will make the<br>
&gt; rules simpler, clearer, and more consistent.<br>
&gt;<br>
&gt; (Everything below here is applying these rules to each of the examples<br>
&gt; used in Dave&#39;s original post.)<br>
&gt;<br>
&gt; print(x) // Guideline 1 prunes argument label<br>
&gt; a.contains(b) // Same<br>
&gt; a.mergeWith(b) // Guideline 1 shortens argument label &quot;WithCollection&quot; to &quot;With&quot;<br>
&gt; // Guideline 2 moves &quot;With&quot; into the base name<br>
&gt;<br>
&gt; a.addGestureRecognizer(x)<br>
&gt; // Guideline 1 does NOT prune &quot;GestureRecognizer&quot; because it would change the semantic meaning<br>
&gt; // Guideline 2 moves it into the base name<br>
&gt;<br>
&gt; - the following 3 examples from the original are treated the same under these rules, for the same reasons mentioned<br>
&gt;&gt;&gt;&gt;&gt;     a.dismiss(b)           // no, unless a is really dismissing b<br>
&gt;&gt;&gt;&gt;&gt;     a.dismissAnimated(b)   // no, not grammatical<br>
&gt;&gt;&gt;&gt;&gt;     a.dismiss(animated: b) // yes, using a label<br>
&gt;<br>
&gt; a.encodeWith(b) // Guideline 1 shortens argument label &quot;WithCoder&quot; to &quot;With&quot;<br>
&gt; // Guideline 2 says put &quot;With&quot; to the base name<br>
&gt;<br>
&gt; a.moveFrom(b, to: c) // Only change to the results of Dave&#39;s examples<br>
&gt; // Guideline 1 shortens &quot;fromScene&quot; to &quot;from&quot; and &quot;toScene&quot; to &quot;to&quot;<br>
&gt; // Exception (b) prevents Guideline 2 from moving &quot;from&quot; into the base name<br>
&gt;<br>
&gt; * Note that I believe the only change to these guidelines required to<br>
&gt; recover the behavior of Dave&#39;s original guidelines is modifying<br>
&gt; Exception (b) to language similar to Dave&#39;s A.<br>
&gt;<br>
&gt; - the following two examples would be covered by Exception (b) as well<br>
&gt;&gt;&gt;&gt;&gt;     a.tracksWith(mediaType: b, composer: c)<br>
&gt;&gt;&gt;&gt;&gt;     a.moveTo(x: 22, y: 99)<br>
&gt;<br>
&gt; Sorry for the long email... Hopefully it&#39;s somewhat useful.<br>
</div></div><div><div class="h5">&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" target="_blank" rel="noreferrer">https://lists.swift.org/mailman/listinfo/swift-evolution</a><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" target="_blank" rel="noreferrer">https://lists.swift.org/mailman/listinfo/swift-evolution</a><br>
</div></div></blockquote></div><br></div></div>