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

[Matthew Judge]

I think part of where the current guidelines struggle is the ambiguity of the term "argument label" 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
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"

Both of these are referred to as "argument labels" in the guidelines 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 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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160207/894389f8/attachment.html>