<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"></head><body dir="auto"><div><br>Hi Erica and Dave,</div><div id="AppleMailSignature"><br></div><div id="AppleMailSignature">I personally like it and I agree with all except the following:</div><div id="AppleMailSignature"><br></div><div id="AppleMailSignature">let p = someFont.glyph("propellor")</div><div id="AppleMailSignature">let p = someFont.glyphWithName("propellor")</div><div id="AppleMailSignature"><br></div><div id="AppleMailSignature">I found the second one more clear. I am not familiar with the API and when I read the first one I started wondering what it would do. Then I read glyphWithName() and I knew that I would be getting me a glyph back named "propellor". </div><div id="AppleMailSignature"><br></div><div id="AppleMailSignature">Also, the bullet reads:</div><blockquote type="cite"><div class=""><ul class="" style="box-sizing: border-box; padding: 0px 0px 0px 2em; margin-top: 0px; margin-bottom: 16px;"><li class="" style="box-sizing: border-box;"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><em class="" style="box-sizing: border-box;">Move the first argument label</em> to the base name when it describes a name or identifier that acts as the subject of the base action</span></font></li></ul></div></blockquote><div id="AppleMailSignature">I think it should also mention that the word "Name" and "Identifier" should be omitted from the base name of the function or method. </div><div id="AppleMailSignature"><br></div><div id="AppleMailSignature">Everything else looks great in my opinion. </div><div id="AppleMailSignature"><br></div><div id="AppleMailSignature">Thank you</div><div id="AppleMailSignature"><br></div><div id="AppleMailSignature"><br></div><div id="AppleMailSignature">Sent from my iPhone</div><div><br>On Feb 3, 2016, at 12:07 AM, Erica Sadun via swift-evolution <<a href="mailto:swift-evolution@swift.org">swift-evolution@swift.org</a>> wrote:<br><br></div><blockquote type="cite"><div><meta http-equiv="Content-Type" content="text/html charset=us-ascii"><div class="">Thoughts? Thoughts:</div><div class=""><br class=""></div><div class=""><p style="box-sizing: border-box; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255); margin-top: 0px !important;" class="">Swift prizes clarity. Its parameter labeling system emphasizes self-documentation and guides code production. In nearly every case, labels follow three simple rules:</p><ul style="box-sizing: border-box; padding: 0px 0px 0px 2em; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class=""><li style="box-sizing: border-box;" class="">Skip argument labels for a method or function's first parameter</li><li style="box-sizing: border-box;" class="">Use argument labels for a method or function's subsequent parameters</li><li style="box-sizing: border-box;" class="">Require argument labels for initializers</li></ul><p style="box-sizing: border-box; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class="">These base rules enhance Swift legibility. Unlike other languages whose positional argument names have meaning only within the implementation context, Swift's labels convey use and meaning at the calling site. This creates better communication, enhances maintainability, and adheres to the principle that code is written rarely and read and reviewed often.</p><p style="box-sizing: border-box; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class="">At times, special circumstances may apply to your code as explored in the following rules:</p><ul style="box-sizing: border-box; padding: 0px 0px 0px 2em; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class=""><li style="box-sizing: border-box;" class=""><em style="box-sizing: border-box;" class="">Skip first argument labels</em> when the first argument completes a sentence established in the base name. If the argument describes a call's primary semantics, it does not require a label:</li></ul><div class="highlight highlight-source-swift" style="box-sizing: border-box; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);"><pre style="box-sizing: border-box; overflow: auto; font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace; font-size: 14px; margin-top: 0px; margin-bottom: 0px; line-height: 1.45; padding: 16px; background-color: rgb(247, 247, 247); border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; word-wrap: normal; word-break: normal;" class=""> a<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">.</span><span class="pl-c1" style="box-sizing: border-box; color: rgb(0, 134, 179);">contains</span>(b) <span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// b completes the phrase "a contains b"</span>
a<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">.</span>mergeWith(b) <span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// b completes the phrase "merge with b"</span>
a<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">.</span>readFrom(u, ofType: b) <span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// "a, read from u" describes</span>
<span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// primary semantics so u gets no</span>
<span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// label. </span>
<span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// b is an option that tunes the </span>
<span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// primary semantics</span></pre></div><ul style="box-sizing: border-box; padding: 0px 0px 0px 2em; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class=""><li style="box-sizing: border-box;" class=""><em style="box-sizing: border-box;" class="">Skip the first argument label</em> when a noun in the base name describes the first argument's role.</li></ul><div class="highlight highlight-source-swift" style="box-sizing: border-box; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);"><pre style="box-sizing: border-box; overflow: auto; font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace; font-size: 14px; margin-top: 0px; margin-bottom: 0px; line-height: 1.45; padding: 16px; background-color: rgb(247, 247, 247); border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; word-wrap: normal; word-break: normal;" class=""> a<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">.</span>addObserver(b) <span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// "add b" completes a meaningful sentence that</span>
<span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// defines the intentended semantics. The first</span>
<span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// argument is the "Observer".</span></pre></div><ul style="box-sizing: border-box; padding: 0px 0px 0px 2em; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class=""><li style="box-sizing: border-box;" class=""><em style="box-sizing: border-box;" class="">Move the first argument label</em> to the base name when it describes a name or identifier that acts as the subject of the base action.</li></ul><div class="highlight highlight-source-swift" style="box-sizing: border-box; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);"><pre style="box-sizing: border-box; overflow: auto; font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace; font-size: 14px; margin-top: 0px; margin-bottom: 0px; line-height: 1.45; padding: 16px; background-color: rgb(247, 247, 247); border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; word-wrap: normal; word-break: normal;" class=""> a<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">.</span>transitionToScene(<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">.</span>GreatHall) <span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// yes</span>
a<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">.</span>transitionToSceneWithIdentifier(<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">.</span>GreatHall) <span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// no</span>
<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">let</span> p <span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">=</span> someFont<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">.</span>glyph(<span class="pl-s" style="box-sizing: border-box; color: rgb(24, 54, 145);"><span class="pl-pds" style="box-sizing: border-box;">"</span>propellor<span class="pl-pds" style="box-sizing: border-box;">"</span></span>) <span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// yes</span>
<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">let</span> p <span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">=</span> someFont<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">.</span>glyphWithName(<span class="pl-s" style="box-sizing: border-box; color: rgb(24, 54, 145);"><span class="pl-pds" style="box-sizing: border-box;">"</span>propellor<span class="pl-pds" style="box-sizing: border-box;">"</span></span>) <span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// no</span>
<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">let</span> p <span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">=</span> someFont<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">.</span>glyph(name: <span class="pl-s" style="box-sizing: border-box; color: rgb(24, 54, 145);"><span class="pl-pds" style="box-sizing: border-box;">"</span>propellor<span class="pl-pds" style="box-sizing: border-box;">"</span></span>) <span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// no</span></pre></div><ul style="box-sizing: border-box; padding: 0px 0px 0px 2em; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class=""><li style="box-sizing: border-box;" class=""><em style="box-sizing: border-box;" class="">Move the first argument label</em> to the base name when it describes argument attributes of existing instances.</li></ul><div class="highlight highlight-source-swift" style="box-sizing: border-box; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);"><pre style="box-sizing: border-box; overflow: auto; font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace; font-size: 14px; margin-top: 0px; margin-bottom: 0px; line-height: 1.45; padding: 16px; background-color: rgb(247, 247, 247); border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; word-wrap: normal; word-break: normal;" class=""> a<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">.</span>tracksOfMediaType(<span class="pl-s" style="box-sizing: border-box; color: rgb(24, 54, 145);"><span class="pl-pds" style="box-sizing: border-box;">"</span>Wax Cylinder<span class="pl-pds" style="box-sizing: border-box;">"</span></span>) <span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// yes</span>
a<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">.</span>removeFirstTrackOfMediaType(<span class="pl-s" style="box-sizing: border-box; color: rgb(24, 54, 145);"><span class="pl-pds" style="box-sizing: border-box;">"</span>BetaMax<span class="pl-pds" style="box-sizing: border-box;">"</span></span>) <span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// yes</span>
a<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">.</span>tracks(mediaType: <span class="pl-s" style="box-sizing: border-box; color: rgb(24, 54, 145);"><span class="pl-pds" style="box-sizing: border-box;">"</span>Wax Cylinder<span class="pl-pds" style="box-sizing: border-box;">"</span></span>) <span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// no</span>
a<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">.</span>removeFirstTrack(havingMediaType: <span class="pl-s" style="box-sizing: border-box; color: rgb(24, 54, 145);"><span class="pl-pds" style="box-sizing: border-box;">"</span>BetaMax<span class="pl-pds" style="box-sizing: border-box;">"</span></span>) <span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// no</span></pre></div><ul style="box-sizing: border-box; padding: 0px 0px 0px 2em; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class=""><li style="box-sizing: border-box;" class=""><em style="box-sizing: border-box;" class="">Use first label arguments</em> when the first parameter is semantically distinct from the base name and does not complete a meaningful "sentence"</li></ul><div class="highlight highlight-source-swift" style="box-sizing: border-box; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);"><pre style="box-sizing: border-box; overflow: auto; font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace; font-size: 14px; margin-top: 0px; margin-bottom: 0px; line-height: 1.45; padding: 16px; background-color: rgb(247, 247, 247); border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; word-wrap: normal; word-break: normal;" class=""> a<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">.</span>dismiss(animated: b) <span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// "a, dismiss b" is a sentence but </span>
<span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// doesn't describe the semantics at all, </span>
<span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// thus we add a label for b.</span></pre></div><ul style="box-sizing: border-box; padding: 0px 0px 0px 2em; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class=""><li style="box-sizing: border-box;" class=""><em style="box-sizing: border-box;" class="">Use all argument labels</em> when the relationship between arguments is semantically stronger than the relationship between the first argument and the base name.</li></ul><div class="highlight highlight-source-swift" style="box-sizing: border-box; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);"><pre style="box-sizing: border-box; overflow: auto; font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace; font-size: 14px; margin-top: 0px; margin-bottom: 0px; line-height: 1.45; padding: 16px; background-color: rgb(247, 247, 247); border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; word-wrap: normal; word-break: normal;" class=""> moveTo(x: a, y: b)
login(userName: a, password: b)
constructColor(red: r, green: g, blue: b, alpha: a)</pre></div><ul style="box-sizing: border-box; padding: 0px 0px 0px 2em; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class=""><li style="box-sizing: border-box;" class=""><em style="box-sizing: border-box;" class="">Omit labels</em> for argument peers that cannot be usefully distinguished.</li></ul><div class="highlight highlight-source-swift" style="box-sizing: border-box; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);"><pre style="box-sizing: border-box; overflow: auto; font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace; font-size: 14px; margin-top: 0px; margin-bottom: 0px; line-height: 1.45; padding: 16px; background-color: rgb(247, 247, 247); border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; word-wrap: normal; word-break: normal;" class=""> <span class="pl-c1" style="box-sizing: border-box; color: rgb(0, 134, 179);">min</span>(number1, number2)
<span class="pl-c1" style="box-sizing: border-box; color: rgb(0, 134, 179);">zip</span>(sequence1, sequence2)</pre></div><ul style="box-sizing: border-box; padding: 0px 0px 0px 2em; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class=""><li style="box-sizing: border-box;" class=""><em style="box-sizing: border-box;" class="">Use explicit argument labels</em> to describe attributes of an instance that's <em style="box-sizing: border-box;" class="">being created</em>. Your calls should resemble initializers.</li></ul><pre style="box-sizing: border-box; overflow: auto; font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace; margin-top: 0px; margin-bottom: 16px; line-height: 1.45; padding: 16px; background-color: rgb(247, 247, 247); border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; word-wrap: normal; color: rgb(51, 51, 51);" class=""><code style="box-sizing: border-box; font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace; padding: 0px; margin: 0px; background-color: transparent; border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; word-break: normal; border: 0px; display: inline; line-height: inherit; word-wrap: normal;" class=""> AudioTrack(mediaType: "BetaMax") // initializer
trackFactory.newTrack(mediaType: "Wax Cylinder") // yes
trackFactory.newTrackOfMediaType("Wax Cylinder") // no
</code></pre><ul style="box-sizing: border-box; padding: 0px 0px 0px 2em; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class=""><li style="box-sizing: border-box;" class=""><em style="box-sizing: border-box;" class="">Use first argument labels</em> that would have normally appeared in the base name when building groups of related calls whose implementations are distinguished specifically by their parameters. Your calls should resemble initializers. </li></ul><div class="highlight highlight-source-swift" style="box-sizing: border-box; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);"><pre style="box-sizing: border-box; overflow: auto; font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace; font-size: 14px; margin-top: 0px; margin-bottom: 0px; line-height: 1.45; padding: 16px; background-color: rgb(247, 247, 247); border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; word-wrap: normal; word-break: normal;" class=""> login(userName: a, password: b) <span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// not loginWithUserName(a, password: b)</span>
login(credential: a) <span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// not loginWithCredential(a)</span></pre></div><ul style="box-sizing: border-box; padding: 0px 0px 0px 2em; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class=""><li style="box-sizing: border-box;" class=""><em style="box-sizing: border-box;" class="">Skip first argument labels</em> for initializers when using full width type conversions, that is when initializing from instances of another type.</li></ul><div class="highlight highlight-source-swift" style="box-sizing: border-box; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);"><pre style="box-sizing: border-box; overflow: auto; font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace; font-size: 14px; margin-top: 0px; margin-bottom: 0px; line-height: 1.45; padding: 16px; background-color: rgb(247, 247, 247); border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; word-wrap: normal; word-break: normal;" class=""> <span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">extension</span> <span class="pl-c1" style="box-sizing: border-box; color: rgb(0, 134, 179);">String</span> {
<span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// Convert `x` into its textual representation </span>
<span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// in the given radix</span>
<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">init</span>(_ x: BigInt, radix: <span class="pl-c1" style="box-sizing: border-box; color: rgb(0, 134, 179);">Int</span> <span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">=</span> <span class="pl-c1" style="box-sizing: border-box; color: rgb(0, 134, 179);">10</span>)
}
text <span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">=</span> <span class="pl-s" style="box-sizing: border-box; color: rgb(24, 54, 145);"><span class="pl-pds" style="box-sizing: border-box;">"</span>The value is: <span class="pl-pds" style="box-sizing: border-box;">"</span></span>
text <span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">+=</span> <span class="pl-c1" style="box-sizing: border-box; color: rgb(0, 134, 179);">String</span>(veryLargeNumber)
text <span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">+=</span> <span class="pl-s" style="box-sizing: border-box; color: rgb(24, 54, 145);"><span class="pl-pds" style="box-sizing: border-box;">"</span> and in hexadecimal, it's<span class="pl-pds" style="box-sizing: border-box;">"</span></span>
text <span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">+=</span> <span class="pl-c1" style="box-sizing: border-box; color: rgb(0, 134, 179);">String</span>(veryLargeNumber, radix: <span class="pl-c1" style="box-sizing: border-box; color: rgb(0, 134, 179);">16</span>)</pre></div><ul style="box-sizing: border-box; padding: 0px 0px 0px 2em; margin-top: 0px; margin-bottom: 16px; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255);" class=""><li style="box-sizing: border-box;" class=""><em style="box-sizing: border-box;" class="">Use first argument labels</em> when narrowing initial values to make it conform to restrictions within the new type. The label should describe how the instance will be modified:</li></ul><div class="highlight highlight-source-swift" style="box-sizing: border-box; color: rgb(51, 51, 51); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; background-color: rgb(255, 255, 255); margin-bottom: 0px !important;"><pre style="box-sizing: border-box; overflow: auto; font-family: Consolas, 'Liberation Mono', Menlo, Courier, monospace; font-size: 14px; margin-top: 0px; margin-bottom: 0px; line-height: 1.45; padding: 16px; background-color: rgb(247, 247, 247); border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; word-wrap: normal; word-break: normal;" class=""> <span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">extension</span> <span class="pl-c1" style="box-sizing: border-box; color: rgb(0, 134, 179);">UInt32</span> {
<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">init</span>(_ value: <span class="pl-c1" style="box-sizing: border-box; color: rgb(0, 134, 179);">Int16</span>) <span class="pl-c" style="box-sizing: border-box; color: rgb(150, 152, 150);">// Widening, so no label </span>
<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">init</span>(truncating bits: <span class="pl-c1" style="box-sizing: border-box; color: rgb(0, 134, 179);">UInt64</span>)
<span class="pl-k" style="box-sizing: border-box; color: rgb(167, 29, 93);">init</span>(saturating value: <span class="pl-c1" style="box-sizing: border-box; color: rgb(0, 134, 179);">UInt64</span>)
}</pre></div><div class=""><br class=""></div></div><div class=""><br class=""></div><div class="">-- E</div><div class=""><br class=""></div><br class=""><div><blockquote type="cite" class=""><div class="">On Feb 2, 2016, at 5:32 PM, Dave Abrahams via swift-evolution <<a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div class=""><br class="">This thread is related to the review of new API guidelines, but it's not<br class="">a review thread; it's exploratory. The goal is to come up with<br class="">guidelines that:<br class=""><br class="">* describe when and where to use argument labels<br class="">* require labels in many of the cases people have asked for them<br class="">* are understandable by humans<br class="">* preserve important semantics communicated by existing APIs.<br class=""><br class="">Here's what I'm thinking<br class=""><br class="">1. If and only if the first argument could complete a sentence*<br class=""> beginning in the base name and describing the primary semantics of<br class=""> the call, it gets no argument label:<br class=""><br class=""> a.contains(b) // b completes the phrase "a contains b"<br class=""> a.mergeWith(b) // b completes the phrase "merge with b"<br class=""><br class=""> a.dismiss(animated: b) // "a, dismiss b" is a sentence but <br class=""> // doesn't describe the semantics at all, <br class=""> // thus we add a label for b.<br class=""><br class=""> a.moveTo(x: 300, y: 400) // "a, move to 300" is a sentence <br class=""> // but doesn't describe the primary <br class=""> // semantics, which are to move in both<br class=""> // x and y. Thus, x gets a label.<br class=""><br class=""> a.readFrom(u, ofType: b) // "a, read from u" describes<br class=""> // the primary semantics, so u gets no<br class=""> // label. b is an<br class=""> // option that tunes the primary<br class=""> // semantics<br class=""><br class=""> [Note that this covers all the direct object cases and, I believe,<br class=""> all the default argument cases too, so maybe that exception can be<br class=""> dropped. We still need the exceptions for full-width type<br class=""> conversions and indistinguishable peers]<br class=""><br class=""> Note: when there is a noun in the base name describing the role of the<br class=""> first argument, we skip it in considering this criterion:<br class=""><br class=""> a.addObserver(b) // "a, add b" completes a sentence describing <br class=""> // the semantics. "Observer" is omitted in <br class=""> // making this determination.<br class=""><br class="">* We could say "clause" here but I think making it an *independent*<br class=""> clause doesn't rule out any important use-cases (see<br class=""> <a href="https://web.cn.edu/kwheeler/gram_clauses_n_phrases.html" class="">https://web.cn.edu/kwheeler/gram_clauses_n_phrases.html</a>) and at that<br class=""> point, you might as well say "sentence," which is a more<br class=""> universally-understood term.<br class=""><br class="">2. Words that describe attributes of an *already-existing* instance<br 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=""><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=""><br class="">Thoughts?<br class=""><br class="">-- <br class="">-Dave<br class=""><br class="">_______________________________________________<br class="">swift-evolution mailing list<br class=""><a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a><br class=""><a href="https://lists.swift.org/mailman/listinfo/swift-evolution">https://lists.swift.org/mailman/listinfo/swift-evolution</a><br class=""></div></div></blockquote></div><br class=""></div></blockquote><blockquote type="cite"><div><span>_______________________________________________</span><br><span>swift-evolution mailing list</span><br><span><a href="mailto:swift-evolution@swift.org">swift-evolution@swift.org</a></span><br><span><a href="https://lists.swift.org/mailman/listinfo/swift-evolution">https://lists.swift.org/mailman/listinfo/swift-evolution</a></span><br></div></blockquote></body></html>