Hi Adrian, Charlie,

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.

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 in the array vs the array 
itself.

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:).

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).

- Tony

> On Oct 14, 2016, at 7:49 AM, Adrian Zubarev via swift-evolution 
> <swift-evolution@swift.org> wrote:
> 
> I’m still not convinced in some cases.
> 
> Take a look at UIViews and its method addSubview.
> 
> open func addSubview(_ view: UIView)
> Personally I’d change or write this function like so:
> 
> open func add(subview: UIView)
> This reduces unnecessary noise _ view for both the implementation and usage.
> 
> // Implementation
> open func add(subview: UIView) {
>     // `subview` is descriptive and just fine here
> }
> 
> // Usage
> 
> self.view.add(subview: someOtherView)
> 
> 
> 
> -- 
> Adrian Zubarev
> Sent with Airmail
> 
> Am 14. Oktober 2016 um 16:42:06, Zach Waldowski via swift-evolution 
> (swift-evolution@swift.org <mailto:swift-evolution@swift.org>) schrieb:
> 
>> The base name of the function describes its core purpose.
>> 
>> There is no ambiguity instructing an Array to "append" something, but
>> there is context needed: "what are we appending? The contents of the
>> newElements parameter." But there is ambiguity asking URL to "give me a
>> new URL by appending". Appending what? Similarly, telling a collection
>> to "replace". Replace what?
>> 
>> A rule of thumb my team has applied is to put the parameter parens where
>> you would have put `with` in ObjC. This is instructive for your
>> questions as well. "URLByAppendingWithPathComponent" and
>> "replaceWithSubrange" wouldn't make sense, but "appendWithContentsOf"
>> does.
>> 
>> Cheers!
>>   Zachary Waldowski
>>   z...@waldowski.me
>> 
>> On Thu, Oct 13, 2016, at 10:30 PM, Charlie Monroe via swift-evolution
>> wrote:
>> > Hi there,
>> > 
>> > I am really grateful for the API guidelines that were created as part of
>> > Swift 3, however, I'm having trouble with distinguishing which part of
>> > the method name should be already an argument. To illustrate this, here
>> > are two examples:
>> > 
>> > // On Array
>> > public mutating func append(contentsOf newElements: S)
>> > 
>> > // On Foundation.URL
>> > public func appendingPathComponent(_ pathComponent: String) -> URL
>> > 
>> > 
>> > Is there a particular reason why it's not
>> > 
>> > public func appending(pathComponent: String) -> URL
>> > 
>> > ?
>> > 
>> > In my opinion the entire stdlib and Foundation is full of such
>> > discrepancies which make it hard to decide when you name your own methods
>> > since there are preceding cases in the language itself (or Foundation)
>> > that go both ways.
>> > 
>> > The same goes for why don't the replace methods (this is on String)
>> > follow the same - when there is append(contentsOf:):
>> > 
>> > public mutating func replaceSubrange(_ bounds: ClosedRange<String.Index>,
>> > with newElements: String)
>> > 
>> > instead of
>> > 
>> > public mutating func replace(subrange bounds: ClosedRange<String.Index>,
>> > with newElements: String)
>> > 
>> > 
>> > 
>> > I know there was an extensive discussion about this here when the stdlib
>> > names were discussed. And given that these would be breaking changes, I
>> > don't necessarily want to start a lengthy discussion about renaming those
>> > again - I'm just wondering what are the reasons behind this and what
>> > should be the correct naming conventions.
>> > 
>> > Thanks!
>> > 
>> > Charlie
>> > _______________________________________________
>> > swift-evolution mailing list
>> > swift-evolution@swift.org
>> > https://lists.swift.org/mailman/listinfo/swift-evolution
>> _______________________________________________
>> swift-evolution mailing list
>> swift-evolution@swift.org
>> https://lists.swift.org/mailman/listinfo/swift-evolution
> 
> 
> _______________________________________________
> swift-evolution mailing list
> swift-evolution@swift.org <mailto:swift-evolution@swift.org>
> https://lists.swift.org/mailman/listinfo/swift-evolution 
> <https://lists.swift.org/mailman/listinfo/swift-evolution>

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

Reply via email to