<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="">This all looks good to me (aside from the linguistic problems with verb conjugation I've raised in another subthread). However, I think these naming guidelines lead us to reconsider our default argument labeling rules for 'func' declarations again, as David Owens and others have suggested. The stated goal of the current language rule is to guide people into good API design following our conventions, but I don't think it succeeds in serving that purpose. If you follow the guidelines, the argument labels for your secondary arguments generally end up becoming prepositional phrases, which make for poor variable names, and you're naturally guided to giving the argument an explicit descriptive binding name:<div class=""><br class=""></div><blockquote style="margin: 0 0 0 40px; border: none; padding: 0px;" class=""><div class="">func perform(stuff: Stuff, with: Thing) {</div></blockquote><blockquote style="margin: 0 0 0 40px; border: none; padding: 0px;" class=""><div class=""> with.apply(stuff) // 'with' is a weird variable name</div><div class="">}</div><div class=""><br class=""></div><div class="">func perform(stuff: Stuff, with thing: Thing) {</div><div class=""> thing.apply(stuff) // 'thing' is better</div><div class="">}</div><div class=""><br class=""></div></blockquote>The shorthand thus doesn't save the good API citizen from much work. On the other hand, a developer who's unaware or uninterested in the guidelines and is just trying to C or Java in Swift gets argument labels by default that neither follow the guidelines nor meet their expectation:<div class=""><br class=""></div><blockquote style="margin: 0 0 0 40px; border: none; padding: 0px;" class=""><div class="">func atan2(y: Double, x: Double) -> Double { ... }</div><div class=""><br class=""></div><div class="">atan2(10, 10) // Why doesn't this work?</div><div class="">atan2(10, x: 10) // Nobody wants this</div><div class=""><br class=""></div></blockquote><div class="">And when staring down potentially dozens or hundreds of compile errors at various mismatched use sites, they're unlikely to reconsider their API naming choice, and will instead do the minimal amount of work to get their code to compile by suppressing the argument label. The language hasn't led this developer to better conventional API design either.</div><div class=""><br class=""></div><div class="">I can think of a couple possible modifications to the language rule that could help reduce the surprise factor, and still lead people to good API design:</div><div class=""><br class=""></div><div class="">- Require all 'func' arguments after the first to explicitly specify both a label and a binding name. Users following the guidelines will usually end up doing this anyway, and users who aren't will get a helpful message instead of unexpected behavior. This also avoids a problem with our current rule, where otherwise identical-looking parameter declarations in a 'func' end up behaving differently based on position. A diagnostic immediately at the declaration site also seems more likely to me to lead the developer to think more about their API naming; diagnosing call sites that don't look the way they want is just going to lead them to reactively suppress the labels to get their code to compile.</div><div class="">- Change the default rule so that all arguments *after an explicitly labeled argument* default to being labeled (instead of all arguments after the first). It's unlikely anyone wants an unlabeled argument positionally after a labeled one, and the rare methods in Cocoa that take more than two arguments do tend to use noun rather than preposition phrases for arguments after the second. Users following the guidelines get nice labeled APIs, and users who aren't get the bare, uncaring anonymous arguments they deserve:</div><div class=""><br class=""></div><blockquote style="margin: 0 0 0 40px; border: none; padding: 0px;" class=""><div class="">func perform(stuff: Stuff, with thing: Thing, options: StuffOptions) // perform(_:with:options:)</div><div class="">func atan2(y: Double, x: Double) // atan2(_:_:)</div><div class=""><br class=""></div></blockquote>-Joe<br class=""><div class=""><div class=""><div class=""><br class=""><div><blockquote type="cite" class=""><div class="">On Jan 22, 2016, at 1:02 PM, Douglas Gregor 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=""><meta http-equiv="Content-Type" content="text/html charset=us-ascii" class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><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="">Hello Swift community,</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="">The review of SE-0023"API Design Guidelines" begins now and runs through January 31, 2016. The proposal is available here:</p><blockquote style="box-sizing: border-box; margin: 0px 0px 16px; padding: 0px 15px; border-left-width: 4px; border-left-style: solid; border-left-color: rgb(221, 221, 221); background-color: rgb(255, 255, 255);" class=""><div style="box-sizing: border-box; margin-top: 0px; margin-bottom: 0px;" class=""><font color="#777777" face="Helvetica Neue, Helvetica, Segoe UI, Arial, freesans, sans-serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol" size="3" class=""><a href="https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md" class="">https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md</a></font></div></blockquote><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="">Reviews are an important part of the Swift evolution process. All reviews should be sent to the swift-evolution mailing list at</p><blockquote style="box-sizing: border-box; margin: 0px 0px 16px; padding: 0px 15px; color: rgb(119, 119, 119); border-left-width: 4px; border-left-style: solid; border-left-color: rgb(221, 221, 221); 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=""><div style="box-sizing: border-box; margin-top: 0px; margin-bottom: 0px;" class=""><a href="https://lists.swift.org/mailman/listinfo/swift-evolution" style="box-sizing: border-box; background-color: transparent; color: rgb(64, 120, 192); text-decoration: none;" class="">https://lists.swift.org/mailman/listinfo/swift-evolution</a></div></blockquote><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="">or, if you would like to keep your feedback private, directly to the review manager. When replying, please try to keep the proposal link at the top of the message:</p><blockquote style="box-sizing: border-box; margin: 0px 0px 16px; padding: 0px 15px; border-left-width: 4px; border-left-style: solid; border-left-color: rgb(221, 221, 221); background-color: rgb(255, 255, 255);" class=""><p style="color: rgb(119, 119, 119); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; box-sizing: border-box; margin-top: 0px; margin-bottom: 16px;" class="">Proposal link:</p><blockquote style="box-sizing: border-box; margin: 0px 0px 16px; padding: 0px 15px; border-left-width: 4px; border-left-style: solid; border-left-color: rgb(221, 221, 221);" class=""><div style="box-sizing: border-box; margin-top: 0px; margin-bottom: 0px;" class=""><font color="#777777" face="Helvetica Neue, Helvetica, Segoe UI, Arial, freesans, sans-serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol" size="3" class=""><a href="https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md" class="">https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md</a></font></div></blockquote><p style="color: rgb(119, 119, 119); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; box-sizing: border-box; margin-top: 0px; margin-bottom: 16px;" class="">Reply text</p><blockquote style="color: rgb(119, 119, 119); font-family: 'Helvetica Neue', Helvetica, 'Segoe UI', Arial, freesans, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol'; font-size: 16px; box-sizing: border-box; margin: 0px; padding: 0px 15px; border-left-width: 4px; border-left-style: solid; border-left-color: rgb(221, 221, 221);" class=""><div style="box-sizing: border-box; margin-top: 0px; margin-bottom: 0px;" class="">Other replies</div></blockquote></blockquote><h5 style="box-sizing: border-box; margin-top: 1em; margin-bottom: 16px; line-height: 1.4; font-size: 1em; 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'; background-color: rgb(255, 255, 255);" class=""><a id="user-content-what-goes-into-a-review-1" class="anchor" href="https://github.com/apple/swift-evolution#what-goes-into-a-review-1" aria-hidden="true" style="box-sizing: border-box; background-color: transparent; color: rgb(64, 120, 192); text-decoration: none; display: inline-block; padding-right: 2px; margin-left: -18px; line-height: 1.1;"><span aria-hidden="true" class="octicon octicon-link" style="box-sizing: border-box; font-weight: normal; font-size: 16px; line-height: 1; font-family: octicons; display: inline-block; text-rendering: auto; -webkit-font-smoothing: antialiased; -webkit-user-select: none; vertical-align: middle; visibility: hidden;"></span></a>What goes into a review?</h5><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="">The goal of the review process is to improve the proposal under review through constructive criticism and, eventually, determine the direction of Swift. When writing your review, here are some questions you might want to answer in your review:</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="">What is your evaluation of the proposal?</li><li style="box-sizing: border-box;" class="">Is the problem being addressed significant enough to warrant a change to Swift?</li><li style="box-sizing: border-box;" class="">Does this proposal fit well with the feel and direction of Swift?</li><li style="box-sizing: border-box;" class="">If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?</li><li style="box-sizing: border-box;" class="">How much effort did you put into your review? A glance, a quick reading, or an in-depth study?</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="">More information about the Swift evolution process is available at</p><blockquote style="box-sizing: border-box; margin: 0px 0px 16px; padding: 0px 15px; color: rgb(119, 119, 119); border-left-width: 4px; border-left-style: solid; border-left-color: rgb(221, 221, 221); 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=""><div style="box-sizing: border-box; margin-top: 0px; margin-bottom: 0px;" class=""><a href="https://github.com/apple/swift-evolution/blob/master/process.md" style="box-sizing: border-box; background-color: transparent; color: rgb(64, 120, 192); text-decoration: none;" class="">https://github.com/apple/swift-evolution/blob/master/process.md</a></div></blockquote><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="">Thank you,</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="">-Doug Gregor</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="">Review Manager</p></div>_______________________________________________<br class="">swift-evolution mailing list<br class=""><a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a><br class="">https://lists.swift.org/mailman/listinfo/swift-evolution<br class=""></div></blockquote></div><br class=""></div></div></div></body></html>