<div dir="ltr"><div>Proposal link:</div><div><a href="https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md" target="_blank">https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md</a></div><div><br></div><div><div>> What is your evaluation of the proposal?</div><div><br></div><div>I think there are more things which would make a "guidelines" document even better for promoting consistent code:</div><div><br></div><div>- When to use functions vs. properties for getters. The changes in <a href="https://github.com/apple/swift-evolution/blob/master/proposals/0006-apply-api-guidelines-to-the-standard-library.md" target="_blank">SE-0006</a> include "func min()" and "var underestimatedCount". <a href="https://github.com/apple/swift-evolution/blob/master/proposals/0005-objective-c-name-translation.md" target="_blank">SE-0005</a> includes "class func darkGray()". I imagine it should be implied that properties are more efficient to compute, but this doesn't seem to be applied consistently.</div><div><br></div><div>- Edge cases of naming, such as what to do with acronyms (like URL) when they appear in function and variable names, especially at the beginning.</div><div><div><br></div><div>- When to use structs/classes/enums; when to use optionals; other such basic API design topics.</div></div><div><br></div><div>While certainly not everything from the <a href="https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html" target="_blank">Coding Guidelines for Cocoa</a> (linked from SE-0005) applies to Swift, the Swift guidelines would do well to match its thoroughness.</div><div><br></div><div><br></div><div> Protocols that describe what something is should read as nouns (e.g. Collection).</div><div> Protocols that describe a capability should be named using the suffixes able, ible, or ing (e.g. Equatable, ProgressReporting).<br></div><div><br></div><div>"SetAlgebra" (from SE-0006) doesn't really fit in with this.</div><div><br></div><div><br></div><div>Extremely minor:</div><div><div> text = "The value is: "</div><div> text += String(veryLargeNumber)</div><div> text += " and in hexadecimal, it's"</div><div> text += String(veryLargeNumber, radix: 16)</div></div><div><br></div><div>The second string literal should have a space at the end as well as the beginning.</div><div><br></div><div><br></div><div>> Is the problem being addressed significant enough to warrant a change to Swift?</div><div><br></div><div>Having a set of guidelines is important.</div><div><br></div><div><br></div><div>> Does this proposal fit well with the feel and direction of Swift?</div><div><br></div><div>Yes.</div><div><br></div><div><br></div><div>> How much effort did you put into your review? A glance, a quick reading, or an in-depth study?</div></div><div><br></div><div>Fairly in-depth.</div><div class="gmail_extra"><br clear="all"><div><div><div dir="ltr"><div>Jacob<br></div></div></div></div>
<br><div class="gmail_quote">On Fri, Jan 22, 2016 at 1:02 PM, Douglas Gregor via swift-evolution <span dir="ltr"><<a href="mailto:swift-evolution@swift.org" target="_blank">swift-evolution@swift.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div style="word-wrap:break-word"><p style="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)">Hello Swift community,</p><p style="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)">The review of SE-0023"API Design Guidelines" begins now and runs through January 31, 2016. The proposal is available here:</p><blockquote style="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)"><div style="margin-top:0px;margin-bottom:0px"><font color="#777777" face="Helvetica Neue, Helvetica, Segoe UI, Arial, freesans, sans-serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol" size="3"><a href="https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md" target="_blank">https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md</a></font></div></blockquote><p style="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)">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="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)"><div style="margin-top:0px;margin-bottom:0px"><a href="https://lists.swift.org/mailman/listinfo/swift-evolution" style="color:rgb(64,120,192);text-decoration:none;background-color:transparent" target="_blank">https://lists.swift.org/mailman/listinfo/swift-evolution</a></div></blockquote><p style="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)">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="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)"><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;margin-top:0px;margin-bottom:16px">Proposal link:</p><blockquote style="margin:0px 0px 16px;padding:0px 15px;border-left-width:4px;border-left-style:solid;border-left-color:rgb(221,221,221)"><div style="margin-top:0px;margin-bottom:0px"><font color="#777777" face="Helvetica Neue, Helvetica, Segoe UI, Arial, freesans, sans-serif, Apple Color Emoji, Segoe UI Emoji, Segoe UI Symbol" size="3"><a href="https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md" target="_blank">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;margin-top:0px;margin-bottom:16px">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;margin:0px;padding:0px 15px;border-left-width:4px;border-left-style:solid;border-left-color:rgb(221,221,221)"><div style="margin-top:0px;margin-bottom:0px">Other replies</div></blockquote></blockquote><h5 style="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)"><a href="https://github.com/apple/swift-evolution#what-goes-into-a-review-1" style="color:rgb(64,120,192);text-decoration:none;display:inline-block;padding-right:2px;line-height:1.1;background-color:transparent" target="_blank"><span style="font-weight:normal;font-size:16px;line-height:1;font-family:octicons;display:inline-block;color:rgb(0,0,0);vertical-align:middle"></span></a>What goes into a review?</h5><p style="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)">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="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)"><li>What is your evaluation of the proposal?</li><li>Is the problem being addressed significant enough to warrant a change to Swift?</li><li>Does this proposal fit well with the feel and direction of Swift?</li><li>If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?</li><li>How much effort did you put into your review? A glance, a quick reading, or an in-depth study?</li></ul><p style="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)">More information about the Swift evolution process is available at</p><blockquote style="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)"><div style="margin-top:0px;margin-bottom:0px"><a href="https://github.com/apple/swift-evolution/blob/master/process.md" style="color:rgb(64,120,192);text-decoration:none;background-color:transparent" target="_blank">https://github.com/apple/swift-evolution/blob/master/process.md</a></div></blockquote><p style="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)">Thank you,</p><p style="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)">-Doug Gregor</p><p style="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)">Review Manager</p></div><br>_______________________________________________<br>
swift-evolution mailing list<br>
<a href="mailto:swift-evolution@swift.org" target="_blank">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>
<br></blockquote></div><br></div></div>