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

[Matthew Judge]

On Mon, Feb 8, 2016 at 12:45 AM, Dave Abrahams via swift-evolution <
swift-evolution at swift.org> wrote:

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

Agreed - I was just trying to distinguish between the two concepts.


> > 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?
>


I don't so much want to redefine "argument label" as have a term to
describe this concept.


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

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.


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

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:
 a.add(gestureRecognizer: b)
 a.addGestureRecognizer(b)
 and the reason we omit the argument label (original definition) in the
following are different.
 anArray.add(b) // Prune "Element" w/o changing semantic meaning
 a.addGestureRecognizer(b) // Words describing the first argument are
already in the base name


>
>
> > 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
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160208/4f56aba0/attachment.html>