[swift-evolution] When to use argument labels, part DEUX

[Dave Abrahams]

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
labels.

> 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
> any)
>
> 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
>
> a.addGestureRecognizer(x)
> // 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
> https://lists.swift.org/mailman/listinfo/swift-evolution

-- 
-Dave