[swift-evolution] [Discussion] API Guidelines

[Adrian Zubarev]

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) 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20161014/86d3a35b/attachment.html>