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.
I find that… surprising.
Between these two (sorry to repeat the same example again):
func trackWith(trackID trackID: CMPersistentTrackID) -> AVAssetTrack?
func track(withTrackID trackID: CMPersistentTrackID) -> AVAssetTrack?
#1 seems nicer and clearer to me. Having “with” as the first word glued to a parameter label looks bizarre to my eyes:
As far as I understand it, the whole reason to keep “with” etc in many APIs was to make cases like this one clearer. Because “track” as a name doesn’t tell you much. Someone said that having the method name end with “With” creates a sense of suspense, and to me that was precisely what was a good thing about it. It’s not just “track”, it’s a “track with” — ooh, here come the criteria for the track! Having removed “with” from the name itself, we lose, IMHO, the clarity this word was supposed to bring in initializer/getter/finder-like methods. And we still keep the word later inside the parens, but to my eyes it no longer helps clarity, just exists as a vacuous, needless word.
Another reason I don’t like this, say we have:
a.tracks(withMediaType: b, composer: c)
This no longer looks symmetrical across the parameters. First parameter has label “with”, second doesn’t. The previous version:
a.tracksWith(mediaType: b, composer: c)
Didn’t have that problem.
I fear that people will take that as a signal that they should make the whole method, including parameter labels, sound like an English sentence and will start applying needless words like “and”:
a.tracks(withMediaType: b, andComposer: c)
To avoid this weird-looking construct where the first parameter has a starting preposition, and other parameters don’t. Again:
a.tracksWith(mediaType: b, composer: c)
Doesn’t have this problem, because while the method name part ends with “With”, the parameters are consistently just nouns.
So -1 from me on this. Moving prepositions inside parens look like a step back from the Part DEUX Proposal.
Would you mind elaborating on the working group's rationale for moving prepositions inside parens?
— Radek
···
On 09 Feb 2016, at 20:18, Dave Abrahams via swift-evolution <swift-evolution@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@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution