<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"><<a href="mailto:swift-evolution@swift.org" target="_blank">swift-evolution@swift.org</a>></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 <<a href="mailto:swift-evolution@swift.org">swift-evolution@swift.org</a>> wrote:<br>
<br>
</span><span>> I think part of where the current guidelines struggle is the ambiguity<br>
> of the term "argument label"<br>
<br>
</span>There's nothing ambiguous about it; it's the thing you write, with a<br>
trailing colon, before an argument in an argument list.<br>
<span><br>
> so just for the sake of discussion I'm going to define terms to be<br>
> explicit (not saying these are precisely the right terms).<br>
><br>
> - External parameter names: names used to refer to parameters at the<br>
> use site<br>
<br>
</span>But they don't refer to parameters; they introduce arguments.<br>
<br>
moveFrom(x, to: y)<br>
<br>
“to” introduces an argument. That's why we'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>
> a.moveTo(x: 1, y: 2) // external parameter names are "x" and "y"<br>
> a.addGestureRecognizer(b) // does not have an external parameter name<br>
><br>
> - Argument labels: words used to describe the argument being passed in<br>
> a.moveTo(x: 1, y: 2) // argument labels are "x" and "y"<br>
> a.addGestureRecognizer(b) // argument label is "GestureRecognizer"<br>
<br>
</span>Now you're redefining “argument label.” Why?<br></blockquote><div><br></div><div><br>I don't so much want to redefine "argument label" 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>
> Both of these are referred to as "argument labels" 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: "first argument is part of a prepositional phrase, put the parenthesis immediately after the preposition." as "move the preposition from the first argument label into the base name" but you're right, your language doesn'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>
> and most of the discussion, but they are slightly different (though<br>
> overlapping) things. For instance, B.1 refers to "external parameter<br>
> names" and B.2 refers to "argument labels"<br>
<br>
</span>I think you've misread the language there. Would you mind re-evaluating<br>
the rest of what you'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'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 "argument label"... The reason we keep "gestureRecognizer" 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 "Element" 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>
> I think my distinction between these terms makes the guidelines simpler with fewer caveats:<br>
><br>
> 1. Prune needless and redundant words from the argument labels<br>
> (i.e. remove any word that can be removed without confusing the<br>
> semantic intent)<br>
> 2. If the method reads as part of a grammatical phrase, prefer to<br>
> locate the first argument label as part of the base name instead of as<br>
> an external parameter name.<br>
> Special Cases/Exceptions:<br>
> a. Arguments with a default value should use an external parameter name<br>
> b. Arguments with similar semantic importance should be treated the<br>
> same (use external parameter names for argument labels or don't label<br>
> any)<br>
><br>
> Not saying these are right/perfect, but I do think the distinction of<br>
> guidelines for argument labels and external parameter will make the<br>
> rules simpler, clearer, and more consistent.<br>
><br>
> (Everything below here is applying these rules to each of the examples<br>
> used in Dave's original post.)<br>
><br>
> print(x) // Guideline 1 prunes argument label<br>
> a.contains(b) // Same<br>
> a.mergeWith(b) // Guideline 1 shortens argument label "WithCollection" to "With"<br>
> // Guideline 2 moves "With" into the base name<br>
><br>
> a.addGestureRecognizer(x)<br>
> // Guideline 1 does NOT prune "GestureRecognizer" because it would change the semantic meaning<br>
> // Guideline 2 moves it into the base name<br>
><br>
> - the following 3 examples from the original are treated the same under these rules, for the same reasons mentioned<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>
> a.encodeWith(b) // Guideline 1 shortens argument label "WithCoder" to "With"<br>
> // Guideline 2 says put "With" to the base name<br>
><br>
> a.moveFrom(b, to: c) // Only change to the results of Dave's examples<br>
> // Guideline 1 shortens "fromScene" to "from" and "toScene" to "to"<br>
> // Exception (b) prevents Guideline 2 from moving "from" into the base name<br>
><br>
> * Note that I believe the only change to these guidelines required to<br>
> recover the behavior of Dave's original guidelines is modifying<br>
> Exception (b) to language similar to Dave's A.<br>
><br>
> - the following two examples would be covered by Exception (b) as well<br>
>>>>> a.tracksWith(mediaType: b, composer: c)<br>
>>>>> a.moveTo(x: 22, y: 99)<br>
><br>
> Sorry for the long email... Hopefully it's somewhat useful.<br>
</div></div><div><div class="h5">> _______________________________________________<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>
<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>