<html><head><meta http-equiv="Content-Type" content="text/html charset=us-ascii"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class="">Awesome for putting this together. I think the rules add some needed clarity, but they have the bias that the first argument *should* have a defaulted empty parameter label. I actually think that complicates matters.</div><div class=""><br class=""></div><div class="">Instead, if the premise was that the first argument is treated no differently then other arguments, then the rule becomes simply a list of exceptions on when the label is not necessary:</div><div class=""><br class=""></div><div class=""><i class="">If the argument's purpose in the primary semantics is clear from the name of the function, then no argument label is required (regardless of argument position).</i></div><div class=""><br class=""></div><div class="">To be clear, this rule does not change the API guidelines statement that all labelled arguments should be placed after non-labelled arguments.</div><div class=""><br class=""></div><div class="">Examples:</div><div class=""><br class=""></div><div class=""><b class="">Remove Label(s)</b></div><div class=""><b class=""><br class=""></b></div><blockquote style="margin: 0 0 0 40px; border: none; padding: 0px;" class=""><div class=""><font face="Menlo" class="">a.contains(b) // the question of containment of b in a is the primary semantic</font></div><div class=""><font face="Menlo" class="">a.merging(b) // combining b with a is the primary semantic</font></div><div class=""><font face="Menlo" class=""><br class=""></font></div><div class=""><font face="Menlo" class="">a.moveTo(300, 400) // moving to coordinates is a primary semantic of a</font></div><div class=""><font face="Menlo" class=""> // the labels can be removed when a has a clear semantic</font></div><div class=""><font face="Menlo" class=""> // limitation of a two-pair coordinate system</font></div><div class=""><font face="Menlo" class=""><br class=""></font></div><div class=""><font face="Menlo" class="">a.readFrom(u, ofType: b) // u is clearly the target of the primary semantic</font></div><div class=""><font face="Menlo" class=""> // "reading", ofType labeled as it's a modifier</font></div><div class=""><font face="Menlo" class=""><br class=""></font></div></blockquote><b class="">Keep Label(s) - the default behavior</b><br class=""><blockquote style="margin: 0 0 0 40px; border: none; padding: 0px;" class=""><div class=""><b class=""><br class=""></b></div><div class=""><font face="Menlo" class="">a.dismiss(animated: b) // dismissal is the primary semantic;</font></div><div class=""><font face="Menlo" class=""> // `animated` is a modifier to that semantic, so</font></div><div class=""><font face="Menlo" class=""> // keep the label</font></div><div class=""><font face="Menlo" class=""><br class=""></font></div><div class=""><span style="font-family: Menlo;" class="">a.moveTo(x: 300, y: 400) // moving is the primary semantic, however a</span></div><div class=""><font face="Menlo" class=""> // has no clear semantic limitation to a 2D</font></div><div class=""><font face="Menlo" class=""> // coordinate context so keep the labels</font></div><div class=""><font face="Menlo" class=""><br class=""></font></div><div class=""><span style="font-family: Menlo;" class="">a.read(from: u, ofType: b) // keep from as there is no non-ambiguous semantic</span></div><div class=""><span style="font-family: Menlo;" class=""> // relationship between u and what is being read</span></div><div class=""><span style="font-family: Menlo;" class=""> // without the label. e.g. without from, it's not</span></div><div class=""><font face="Menlo" class=""> // clear that read is reading from u, it could read</font></div><div class=""><font face="Menlo" class=""> // from stdin.</font></div></blockquote><div class=""><br class=""></div><div class="">The `moveTo` example is also an illustration of why `max` would have no labels:</div><div class=""><br class=""></div><div class=""><blockquote style="margin: 0px 0px 0px 40px; border: none; padding: 0px;" class=""><font face="Menlo" class="">max(x, y) // maximum value is primary semantic of the parameter set</font></blockquote></div><div class=""><br class=""></div><div class="">I put the `a.readFrom(_:ofType:)` and `a.read(from:ofType:)` as an illustration of two valid API names that would have different applications of the rule depending on choice of the first part of the function identifier. I'll argue below which I think is better, in the general case, and the modification of rule #2 to support it.</div><div class=""><br class=""></div><div class=""><br class=""></div><div><blockquote type="cite" class=""><div class="">2. Words that describe attributes of an *already-existing* instance</div></blockquote></div><div><blockquote type="cite" class=""><div class=""><div class=""> should go in the base name rather than in a label:<br class=""><br class=""> a.tracksHavingMediaType("Wax Cylinder") // yes<br class=""> a.removeFirstTrackHavingMediaType("BetaMax") // yes<br class=""><br class=""> a.tracks(mediaType: "Wax Cylinder") // no<br class=""> a.removeFirstTrack(havingMediaType: "BetaMax") // no<br class=""><br class=""> [yes, we could use "With" instead of "Having", but it's more<br class=""> ambiguous]<br class=""><br class=""> Words that describe attributes of an instance *to be created* should<br class=""> go in argument labels, rather than the base name (for parity with<br class=""> initializers):<br class=""><br class=""> AudioTrack(mediaType: "BetaMax") // initializer<br class=""> trackFactory.newTrack(mediaType: "Wax Cylinder") // yes<br class=""><br class=""> trackFactory.newTrackWithMediaType("Wax Cylinder") // no<br class=""></div></div></blockquote><div><br class=""></div><div>I see this rule as more about how to name the APIs instead of being about the argument labels. This is also strikes at the root of our fundamental disagreement that we cannot seem to resolve. =)</div><div><br class=""></div><div>You seem to treat the entire function identifier to two disjoint parts (please correct me if I'm misunderstanding you): the base name, including the relationship to the first parameter, and the supporting labels. The base name is the primary indicator of what the function does, with the inclusion of how the first argument relates to that semantic. The remaining argument labels are there mostly as secondary information.</div><div><br class=""></div></div><blockquote style="margin: 0 0 0 40px; border: none; padding: 0px;" class=""><div><div><div><span style="font-family: Menlo;" class="">a.tracksHavingMediaType("Wax Cylinder")</span></div></div></div><div><div><div><font face="Menlo" class="">// identifier: tracksHavingMediaType(_:)</font></div></div></div></blockquote><div><div><div class=""><font face="Menlo" class=""><br class=""></font></div></div><div>However, I treat the entire identifier as a complete whole with no real deference to the base name over the argument labels. So the above example would be broken down like this:</div><div><span style="font-family: Menlo;" class=""><br class=""></span></div></div><blockquote style="margin: 0 0 0 40px; border: none; padding: 0px;" class=""><div><div><span style="font-family: Menlo;" class="">a.tracksHaving(mediaType: "Wax Cylinder")</span></div></div><div><div><div class=""><font face="Menlo" class="">// identifier: tracksHaving(mediaType:)</font></div></div></div></blockquote><div><div><br class=""></div><div>**IF** we start with the premise that argument labels are required by default, the simplified ruleset I used above already answers how to put the label on regardless of which "base name" you chose. </div><div><br class=""></div><div>I would then change rule #2 to this: the "base name" of the function describes the semantic intention while the argument labels are used to describe their relationship to that semantic intention or modification of how that intent is to be carried out.</div><div><br class=""></div><div><blockquote style="margin: 0px 0px 0px 40px; border: none; padding: 0px;" class=""><div><div><div><span style="font-family: Menlo;" class="">a.tracksHavingMediaType("Wax Cylinder") // no, `MediaType` relates to the argument, not</span></div><div><span style="font-family: Menlo;" class=""> // primary intent of the function.</span></div><div><span style="font-family: Menlo;" class=""><br class=""></span></div></div></div><div><div><div><span style="font-family: Menlo;" class="">a.tracksHaving(mediaType: "Wax Cylinder") // yes, the primary intent is to find tracks</span></div><div><span style="font-family: Menlo;" class=""> // based on some criteria. </span></div></div></div></blockquote><blockquote style="margin: 0px 0px 0px 40px; border: none; padding: 0px;" class=""><div><div><br class=""></div></div></blockquote><div></div></div><div>No special rules or exceptions are necessary.</div><br class=""><blockquote type="cite" class=""><div class=""><div class=""><br class="">3. (this one is separable) When the first argument is the *name* or<br class=""> *identifier* of the subject in the base name, do not label it or<br class=""> describe it in the base name.<br class=""><br class=""> a.transitionToScene(.GreatHall) // yes<br class=""> a.transitionToSceneWithIdentifier(.GreatHall) // no<br class=""><br class=""> let p = someFont.glyph("propellor") // yes<br class=""> let p = someFont.glyphWithName("propellor") // no<br class=""> let p = someFont.glyph(name: "propellor") // no<br class=""></div></div></blockquote><div><br class=""></div><div>The labelling piece is already covered by the simplified rule #1 above and by my modified rule #2, so this rule is redundant. `WithIdentifier` and `WithName` should never be present because they belong to the first parameter, not to the semantic intention of the function.</div><div><br class=""></div><div>The choice between `transitionToScene(_:)`, `transitionTo(_:)`, or even `transitionTo(scene:)` is an interesting one. I do not think there is an objectively clear winner based on the limited sample context. Though if we followed the more direct guidance of the modified rule #2, the only real options left would be: `transitionTo(_:)` and `transitionTo(scene:)`.</div><div><br class=""></div><div>If `a` were a scene manager and the only transitioning that would take place, it could be argued that `transitionTo(_:)` is enough.</div><div>If `a` were a general transitioning engine, then `transitionTo(scene:)` would be the choice based on the modified rules #1 and #2 as the semantic intention of transitioning is clear, but the target would not be, so the `scene` label would be kept.</div><div><br class=""></div><div>For clarity: `transitionToScene(_:)` would not be a candidate as rule #2 states that qualifiers for arguments, in this case `Scene`, belong with the argument itself.</div><div><br class=""></div><div>In the very least, I hope this better articulates why I don't prefer the treatment of the first argument as special, and why I do not put first argument information into the "base name" of the function.</div><div><br class=""></div><div>Cheers!</div><div><br class=""></div><div>-David</div><div><br class=""></div><div><br class=""></div><div><div class=""><br class=""></div></div></div></body></html>