[swift-evolution] [Discussion] API Guidelines

[Tony Parker]

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 at 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 at swift.org <mailto:swift-evolution at 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
>>   zach at 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 at swift.org
>> > https://lists.swift.org/mailman/listinfo/swift-evolution
>> _______________________________________________
>> swift-evolution mailing list
>> swift-evolution at swift.org
>> https://lists.swift.org/mailman/listinfo/swift-evolution
> 
> 
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org <mailto:swift-evolution at swift.org>
> https://lists.swift.org/mailman/listinfo/swift-evolution <https://lists.swift.org/mailman/listinfo/swift-evolution>

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20161014/9db82281/attachment.html>