<html><head><meta http-equiv="Content-Type" content="text/html charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class="">Hi Adrian, Charlie,<div class=""><br class=""></div><div class="">One additional thing that we considered when naming methods like this was how central the operation described in the method was to the overall purpose of the type.</div><div class=""><br class=""></div><div class="">For example, the core purpose of an array is to store things. Having functions with a base name of ‘add’ or ‘remove’ makes sense. Also, the array(contentsOf:) is a special case. Array could store other Arrays (Array<Array<T>>), and we needed to disambiguate between appending the stuff <i class="">in</i> the array vs the array itself.</div><div class=""><br class=""></div><div class="">We decided that this was not the case for URL (although clearly reasonable people could disagree — we made a decision and stuck with it). Therefore: appendingPathComponent instead of appending(pathComponent:).</div><div class=""><br class=""></div><div class="">There is no doubt in my mind that these guidelines leave a lot more flexibility to the API designer than similar guidelines for Objective-C. That is probably best at this point. I think we, as a community, are still evolving the best practices. I hope we can learn new patterns and idioms over time as we write more and more Swift API. The Objective-C guidelines have evolved dramatically from when Objective-C was as young as Swift (think about things like not even declaring a method return type and assuming ‘id’, or extending NSObject for so-called “informal protocols”, or even the relatively recent addition of property syntax).</div><div class=""><br class=""></div><div class="">- Tony</div><div class=""><div class=""><br class=""></div><div class=""><div><blockquote type="cite" class=""><div class="">On Oct 14, 2016, at 7:49 AM, Adrian Zubarev 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="bloop_markdown" style="font-family: Helvetica, Arial; font-size: 13px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(254, 254, 254);"><p style="margin: 15px 0px; -webkit-margin-before: 0px;" class="">I’m still not convinced in some cases.</p><p style="margin: 15px 0px;" class="">Take a look at<span class="Apple-converted-space"> </span><code style="font-family: Menlo, Consolas, 'Liberation Mono', Courier, monospace; font-size: 10pt; border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; background-color: rgb(248, 248, 248); color: inherit; border: 1px solid rgb(234, 234, 234); margin: 0px 2px; padding: 0px 5px; word-break: normal; word-wrap: normal; -webkit-margin-before: 0px;" class="">UIView</code>s and its method<span class="Apple-converted-space"> </span><code style="font-family: Menlo, Consolas, 'Liberation Mono', Courier, monospace; font-size: 10pt; border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; background-color: rgb(248, 248, 248); color: inherit; border: 1px solid rgb(234, 234, 234); margin: 0px 2px; padding: 0px 5px; word-break: normal; word-wrap: normal;" class="">addSubview</code>.</p><pre style="margin: 15px 0px; font-family: Menlo, Consolas, 'Liberation Mono', Courier, monospace; font-size: 10pt; border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; background-color: rgb(248, 248, 248); color: inherit; border: 1px solid rgb(204, 204, 204); overflow: auto; padding: 4px 8px; word-break: normal; word-wrap: normal;" class=""><code class="swift" style="font-family: Menlo, Consolas, 'Liberation Mono', Courier, monospace; font-size: 10pt; border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; background-color: rgb(248, 248, 248); color: inherit; border: 0px; margin: 0px; padding: 0px; word-break: normal; word-wrap: normal; -webkit-margin-before: 0px;">open func addSubview(_ view: UIView)
</code></pre><p style="margin: 15px 0px;" class="">Personally I’d change or write this function like so:</p><pre style="margin: 15px 0px; font-family: Menlo, Consolas, 'Liberation Mono', Courier, monospace; font-size: 10pt; border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; background-color: rgb(248, 248, 248); color: inherit; border: 1px solid rgb(204, 204, 204); overflow: auto; padding: 4px 8px; word-break: normal; word-wrap: normal;" class=""><code class="swift" style="font-family: Menlo, Consolas, 'Liberation Mono', Courier, monospace; font-size: 10pt; border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; background-color: rgb(248, 248, 248); color: inherit; border: 0px; margin: 0px; padding: 0px; word-break: normal; word-wrap: normal; -webkit-margin-before: 0px;">open func add(subview: UIView)
</code></pre><p style="margin: 15px 0px;" class="">This reduces unnecessary noise<span class="Apple-converted-space"> </span><code style="font-family: Menlo, Consolas, 'Liberation Mono', Courier, monospace; font-size: 10pt; border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; background-color: rgb(248, 248, 248); color: inherit; border: 1px solid rgb(234, 234, 234); margin: 0px 2px; padding: 0px 5px; word-break: normal; word-wrap: normal; -webkit-margin-before: 0px;" class="">_ view</code><span class="Apple-converted-space"> </span>for both the implementation and usage.</p><pre style="margin: 15px 0px; font-family: Menlo, Consolas, 'Liberation Mono', Courier, monospace; font-size: 10pt; border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; background-color: rgb(248, 248, 248); color: inherit; border: 1px solid rgb(204, 204, 204); overflow: auto; padding: 4px 8px; word-break: normal; word-wrap: normal;" class=""><code class="swift" style="font-family: Menlo, Consolas, 'Liberation Mono', Courier, monospace; font-size: 10pt; border-top-left-radius: 3px; border-top-right-radius: 3px; border-bottom-right-radius: 3px; border-bottom-left-radius: 3px; background-color: rgb(248, 248, 248); color: inherit; border: 0px; margin: 0px; padding: 0px; word-break: normal; word-wrap: normal; -webkit-margin-before: 0px;">// Implementation
open func add(subview: UIView) {
// `subview` is descriptive and just fine here
}
// Usage
self.view.add(subview: someOtherView)
</code></pre><div style="margin: 15px 0px;" class=""><br class="webkit-block-placeholder"></div></div><div class="bloop_original_html" style="font-family: Helvetica, Arial; font-size: 13px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(254, 254, 254);"><div id="bloop_customfont" style="font-family: Helvetica, Arial; font-size: 13px; margin: 0px;" class=""><br class=""></div><br class=""><div id="bloop_sign_1476456293448583168" class="bloop_sign"><div style="font-family: helvetica, arial; font-size: 13px;" class="">-- <br class="">Adrian Zubarev<br class="">Sent with Airmail</div></div><br class=""><p class="airmail_on" style="margin: 15px 0px;">Am 14. Oktober 2016 um 16:42:06, Zach Waldowski via swift-evolution (<a href="mailto:swift-evolution@swift.org" style="color: rgb(65, 131, 196); background-color: inherit; text-decoration: none;" class="">swift-evolution@swift.org</a>) schrieb:</p><blockquote type="cite" class="clean_bq" style="margin: 15px 0px;"><span style="margin-top: 0px; margin-bottom: 0px;" class=""><div class=""><div class=""></div><div class="">The base name of the function describes its core purpose.<br class=""><br class="">There is no ambiguity instructing an Array to "append" something, but<br class="">there is context needed: "what are we appending? The contents of the<br class="">newElements parameter." But there is ambiguity asking URL to "give me a<br class="">new URL by appending". Appending what? Similarly, telling a collection<br class="">to "replace". Replace what?<br class=""><br class="">A rule of thumb my team has applied is to put the parameter parens where<br class="">you would have put `with` in ObjC. This is instructive for your<br class="">questions as well. "URLByAppendingWithPathComponent" and<br class="">"replaceWithSubrange" wouldn't make sense, but "appendWithContentsOf"<br class="">does.<br class=""><br class="">Cheers!<br class=""> Zachary Waldowski<br class=""> <a href="mailto:zach@waldowski.me" class="">zach@waldowski.me</a><br class=""><br class="">On Thu, Oct 13, 2016, at 10:30 PM, Charlie Monroe via swift-evolution<br class="">wrote:<br class="">> Hi there,<br class="">><span class="Apple-converted-space"> </span><br class="">> I am really grateful for the API guidelines that were created as part of<br class="">> Swift 3, however, I'm having trouble with distinguishing which part of<br class="">> the method name should be already an argument. To illustrate this, here<br class="">> are two examples:<br class="">><span class="Apple-converted-space"> </span><br class="">> // On Array<br class="">> public mutating func append(contentsOf newElements: S)<br class="">><span class="Apple-converted-space"> </span><br class="">> // On Foundation.URL<br class="">> public func appendingPathComponent(_ pathComponent: String) -> URL<br class="">><span class="Apple-converted-space"> </span><br class="">><span class="Apple-converted-space"> </span><br class="">> Is there a particular reason why it's not<br class="">><span class="Apple-converted-space"> </span><br class="">> public func appending(pathComponent: String) -> URL<br class="">><span class="Apple-converted-space"> </span><br class="">> ?<br class="">><span class="Apple-converted-space"> </span><br class="">> In my opinion the entire stdlib and Foundation is full of such<br class="">> discrepancies which make it hard to decide when you name your own methods<br class="">> since there are preceding cases in the language itself (or Foundation)<br class="">> that go both ways.<br class="">><span class="Apple-converted-space"> </span><br class="">> The same goes for why don't the replace methods (this is on String)<br class="">> follow the same - when there is append(contentsOf:):<br class="">><span class="Apple-converted-space"> </span><br class="">> public mutating func replaceSubrange(_ bounds: ClosedRange<String.Index>,<br class="">> with newElements: String)<br class="">><span class="Apple-converted-space"> </span><br class="">> instead of<br class="">><span class="Apple-converted-space"> </span><br class="">> public mutating func replace(subrange bounds: ClosedRange<String.Index>,<br class="">> with newElements: String)<br class="">><span class="Apple-converted-space"> </span><br class="">><span class="Apple-converted-space"> </span><br class="">><span class="Apple-converted-space"> </span><br class="">> I know there was an extensive discussion about this here when the stdlib<br class="">> names were discussed. And given that these would be breaking changes, I<br class="">> don't necessarily want to start a lengthy discussion about renaming those<br class="">> again - I'm just wondering what are the reasons behind this and what<br class="">> should be the correct naming conventions.<br class="">><span class="Apple-converted-space"> </span><br class="">> Thanks!<br class="">><span class="Apple-converted-space"> </span><br class="">> Charlie<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" class="">https://lists.swift.org/mailman/listinfo/swift-evolution</a><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="">https://lists.swift.org/mailman/listinfo/swift-evolution<br class=""></div></div></span></blockquote></div><div class="bloop_markdown" style="font-family: Helvetica, Arial; font-size: 13px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(254, 254, 254);"><div style="margin: 15px 0px; -webkit-margin-before: 0px;" class=""><br class="webkit-block-placeholder"></div></div><span style="font-family: Helvetica, Arial; font-size: 13px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(254, 254, 254); float: none; display: inline !important;" class="">_______________________________________________</span><br style="font-family: Helvetica, Arial; font-size: 13px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(254, 254, 254);" class=""><span style="font-family: Helvetica, Arial; font-size: 13px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(254, 254, 254); float: none; display: inline !important;" class="">swift-evolution mailing list</span><br style="font-family: Helvetica, Arial; font-size: 13px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(254, 254, 254);" class=""><a href="mailto:swift-evolution@swift.org" style="color: rgb(65, 131, 196); background-color: rgb(254, 254, 254); text-decoration: none; font-family: Helvetica, Arial; font-size: 13px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px;" class="">swift-evolution@swift.org</a><br style="font-family: Helvetica, Arial; font-size: 13px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(254, 254, 254);" class=""><a href="https://lists.swift.org/mailman/listinfo/swift-evolution" style="color: rgb(65, 131, 196); background-color: rgb(254, 254, 254); text-decoration: none; font-family: Helvetica, Arial; font-size: 13px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-size-adjust: auto; -webkit-text-stroke-width: 0px;" class="">https://lists.swift.org/mailman/listinfo/swift-evolution</a><br style="font-family: Helvetica, Arial; font-size: 13px; font-style: normal; font-variant-caps: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px; background-color: rgb(254, 254, 254);" class=""></div></blockquote></div><br class=""></div></div></body></html>