<div dir="ltr">+1 for 1 and 3<div>-1 for 2</div><div><br></div><div>I didn&#39;t take to 2, the no examples seemed as least as clear as the yes, e.g. I liked:</div><div><br></div><div>    <span style="font-size:13px">a.tracks(mediaType: &quot;Wax Cylinder&quot;)</span></div><div><span style="font-size:13px"><br></span></div><div><span style="font-size:13px">and it is consistent with everything else. Therefore I suggest you just delete clause 2.</span></div><div><span style="font-size:13px"><br></span></div><div><span style="font-size:13px">(Very nice write up of your thoughts!)</span></div><div>  </div></div><div class="gmail_extra"><br><div class="gmail_quote">On 3 February 2016 at 11:32, Dave Abrahams via swift-evolution <span dir="ltr">&lt;<a href="mailto:swift-evolution@swift.org" target="_blank">swift-evolution@swift.org</a>&gt;</span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><br>
This thread is related to the review of new API guidelines, but it&#39;s not<br>
a review thread; it&#39;s exploratory.  The goal is to come up with<br>
guidelines that:<br>
<br>
* describe when and where to use argument labels<br>
* require labels in many of the cases people have asked for them<br>
* are understandable by humans<br>
* preserve important semantics communicated by existing APIs.<br>
<br>
Here&#39;s what I&#39;m thinking<br>
<br>
1. If and only if the first argument could complete a sentence*<br>
   beginning in the base name and describing the primary semantics of<br>
   the call, it gets no argument label:<br>
<br>
     a.contains(b)  // b completes the phrase &quot;a contains b&quot;<br>
     a.mergeWith(b) // b completes the phrase &quot;merge with b&quot;<br>
<br>
     a.dismiss(animated: b) // &quot;a, dismiss b&quot; is a sentence but<br>
                            // doesn&#39;t describe the semantics at all,<br>
                            // thus we add a label for b.<br>
<br>
     a.moveTo(x: 300, y: 400) // &quot;a, move to 300&quot; is a sentence<br>
                              // but doesn&#39;t describe the primary<br>
                              // semantics, which are to move in both<br>
                              // x and y.  Thus, x gets a label.<br>
<br>
     a.readFrom(u, ofType: b) // &quot;a, read from u&quot; describes<br>
                              // the primary semantics, so u gets no<br>
                              // label. b is an<br>
                              // option that tunes the primary<br>
                              // semantics<br>
<br>
   [Note that this covers all the direct object cases and, I believe,<br>
   all the default argument cases too, so maybe that exception can be<br>
   dropped.  We still need the exceptions for full-width type<br>
   conversions and indistinguishable peers]<br>
<br>
   Note: when there is a noun in the base name describing the role of the<br>
   first argument, we skip it in considering this criterion:<br>
<br>
      a.addObserver(b) // &quot;a, add b&quot; completes a sentence describing<br>
                       // the semantics.  &quot;Observer&quot; is omitted in<br>
                       // making this determination.<br>
<br>
* We could say &quot;clause&quot; here but I think making it an *independent*<br>
  clause doesn&#39;t rule out any important use-cases (see<br>
  <a href="https://web.cn.edu/kwheeler/gram_clauses_n_phrases.html" rel="noreferrer" target="_blank">https://web.cn.edu/kwheeler/gram_clauses_n_phrases.html</a>) and at that<br>
  point, you might as well say &quot;sentence,&quot; which is a more<br>
  universally-understood term.<br>
<br>
2. Words that describe attributes of an *already-existing* instance<br>
   should go in the base name rather than in a label:<br>
<br>
      a.tracksHavingMediaType(&quot;Wax Cylinder&quot;)      // yes<br>
      a.removeFirstTrackHavingMediaType(&quot;BetaMax&quot;) // yes<br>
<br>
      a.tracks(mediaType: &quot;Wax Cylinder&quot;)          // no<br>
      a.removeFirstTrack(havingMediaType: &quot;BetaMax&quot;) // no<br>
<br>
   [yes, we could use &quot;With&quot; instead of &quot;Having&quot;, but it&#39;s more<br>
   ambiguous]<br>
<br>
   Words that describe attributes of an instance *to be created* should<br>
   go in argument labels, rather than the base name (for parity with<br>
   initializers):<br>
<br>
      AudioTrack(mediaType: &quot;BetaMax&quot;)                   // initializer<br>
      trackFactory.newTrack(mediaType: &quot;Wax Cylinder&quot;)   // yes<br>
<br>
      trackFactory.newTrackWithMediaType(&quot;Wax Cylinder&quot;) // no<br>
<br>
3. (this one is separable) When the first argument is the *name* or<br>
   *identifier* of the subject in the base name, do not label it or<br>
   describe it in the base name.<br>
<br>
      a.transitionToScene(.GreatHall)               // yes<br>
      a.transitionToSceneWithIdentifier(.GreatHall) // no<br>
<br>
      let p = someFont.glyph(&quot;propellor&quot;)           // yes<br>
      let p = someFont.glyphWithName(&quot;propellor&quot;)   // no<br>
      let p = someFont.glyph(name: &quot;propellor&quot;)     // no<br>
<br>
Thoughts?<br>
<span class="HOEnZb"><font color="#888888"><br>
--<br>
-Dave<br>
<br>
_______________________________________________<br>
swift-evolution mailing list<br>
<a href="mailto:swift-evolution@swift.org">swift-evolution@swift.org</a><br>
<a href="https://lists.swift.org/mailman/listinfo/swift-evolution" rel="noreferrer" target="_blank">https://lists.swift.org/mailman/listinfo/swift-evolution</a><br>
</font></span></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature">  -- Howard.<br></div>
</div>