[swift-evolution] [Guidelines, First Argument Labels]: Prepositions inside the parens
Charles Kissinger
crk at akkyra.com
Thu Feb 11 02:40:23 CST 2016
FWIW, I think these new guidelines strike a very nice balance between all of the competing concerns. The result of applying them to some of my own code could best be described as “different but not unpleasant” ;-)
In looking over the diffs, one nice result I didn’t expect is that moving the prepositional phrases into the first argument label seems to increase the speed with which I absorb the general intent of a function -- the “at a glance” understanding -- by moving a “detail” (important as it might be) into the parameter list. (The split prepositional phrases had the opposite effect for me.)
—CK
> On Feb 9, 2016, at 11:18 AM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
>
>
> Hi everybody,
>
> Having looked at some examples, the API guidelines working group members
> that were present this morning agreed we really want prepositions inside
> the parentheses of method calls.
>
> Here are some results for the importer; we're still tuning some of the
> heuristics but overall we feel very good about the preposition
> placement:
>
> https://github.com/apple/swift-3-api-guidelines-review/commit/da7e512cf75688e6da148dd2a8b27ae9efcb8821?diff=split
>
> Note that this is not final wording, but here are the guidelines we're
> working with for first argument labels:
>
> A. Try to form a grammatical phrase including the first argument and
> describing the primary semantics at the call site.
>
> B. The first argument gets a label when and only when:
>
> 1. It does not form part of a grammatical phrase describing the
> primary semantics. For example,
> ```
> x.dismiss(animated: y)
> ```
> [more examples needed]
> Note that parameters with defaults never describe the primary
> semantics. so are always labeled.
> ```
> func invert(options options: SomeOptionSet = []) // yes
> func invert(_ options: SomeOptionSet = []) // no
> ```
>
> 2. The method is a factory method; such calls should mirror
> initializers, with no preposition. For example,
> ```
> let x = UIColor(red: r, green: g, blue: b)
> let y = monitor.makeColor(red: r, green: g, blue: b)
> ```
>
> 3. It is part of a prepositional phrase
>
> a. The label normally starts with the preposition.
> For example,
> ```
> x.move(from: a, to: b)
> x.loadValues(forKeys: ["fox", "box", "lox"])
> ```
> b. ...unless the preposition would break a very tight association
> between parameters:
> ```
> x.moveTo(x: a, y: b)
> ```
> [encourage grouping parameters into higher-level concepts,
> e.g. Point, in these cases]
>
>
>
> Feedback most welcome, of course.
> --
> -Dave
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution
More information about the swift-evolution
mailing list