[swift-evolution] When to use argument labels, part DEUX
dabrahams at apple.com
Sun Feb 7 23:45:26 CST 2016
on Sun Feb 07 2016, Matthew Judge <swift-evolution at swift.org> wrote:
> I think part of where the current guidelines struggle is the ambiguity
> of the term "argument label"
There's nothing ambiguous about it; it's the thing you write, with a
trailing colon, before an argument in an argument list.
> so just for the sake of discussion I'm going to define terms to be
> explicit (not saying these are precisely the right terms).
> - External parameter names: names used to refer to parameters at the
> use site
But they don't refer to parameters; they introduce arguments.
moveFrom(x, to: y)
“to” introduces an argument. That's why we're calling them argument
> a.moveTo(x: 1, y: 2) // external parameter names are "x" and "y"
> a.addGestureRecognizer(b) // does not have an external parameter name
> - Argument labels: words used to describe the argument being passed in
> a.moveTo(x: 1, y: 2) // argument labels are "x" and "y"
> a.addGestureRecognizer(b) // argument label is "GestureRecognizer"
Now you're redefining “argument label.” Why?
> Both of these are referred to as "argument labels" in the guidelines
Not unless I made a big mistake. It is only supposed to mean what you
are calling an “external parameter name.”
> and most of the discussion, but they are slightly different (though
> overlapping) things. For instance, B.1 refers to "external parameter
> names" and B.2 refers to "argument labels"
I think you've misread the language there. Would you mind re-evaluating
the rest of what you're saying here in that light? I think we need to
start from a common understanding.
> I think my distinction between these terms makes the guidelines simpler with fewer caveats:
> 1. Prune needless and redundant words from the argument labels
> (i.e. remove any word that can be removed without confusing the
> semantic intent)
> 2. If the method reads as part of a grammatical phrase, prefer to
> locate the first argument label as part of the base name instead of as
> an external parameter name.
> Special Cases/Exceptions:
> a. Arguments with a default value should use an external parameter name
> b. Arguments with similar semantic importance should be treated the
> same (use external parameter names for argument labels or don't label
> Not saying these are right/perfect, but I do think the distinction of
> guidelines for argument labels and external parameter will make the
> rules simpler, clearer, and more consistent.
> (Everything below here is applying these rules to each of the examples
> used in Dave's original post.)
> print(x) // Guideline 1 prunes argument label
> a.contains(b) // Same
> a.mergeWith(b) // Guideline 1 shortens argument label "WithCollection" to "With"
> // Guideline 2 moves "With" into the base name
> // Guideline 1 does NOT prune "GestureRecognizer" because it would change the semantic meaning
> // Guideline 2 moves it into the base name
> - the following 3 examples from the original are treated the same under these rules, for the same reasons mentioned
>>>>> a.dismiss(b) // no, unless a is really dismissing b
>>>>> a.dismissAnimated(b) // no, not grammatical
>>>>> a.dismiss(animated: b) // yes, using a label
> a.encodeWith(b) // Guideline 1 shortens argument label "WithCoder" to "With"
> // Guideline 2 says put "With" to the base name
> a.moveFrom(b, to: c) // Only change to the results of Dave's examples
> // Guideline 1 shortens "fromScene" to "from" and "toScene" to "to"
> // Exception (b) prevents Guideline 2 from moving "from" into the base name
> * Note that I believe the only change to these guidelines required to
> recover the behavior of Dave's original guidelines is modifying
> Exception (b) to language similar to Dave's A.
> - the following two examples would be covered by Exception (b) as well
>>>>> a.tracksWith(mediaType: b, composer: c)
>>>>> a.moveTo(x: 22, y: 99)
> Sorry for the long email... Hopefully it's somewhat useful.
> swift-evolution mailing list
> swift-evolution at swift.org
More information about the swift-evolution