[swift-evolution] [Discussion] API Guidelines

[Dave Abrahams]

on Fri Oct 14 2016, Adrian Zubarev <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.

No, the usage is either v1.addSubview(v2) or v1.add(subview: v2) Neither
usage introduces an underscore.  To a first approximation, how the
implementation looks is irrelevant.  APIs are used many more times than
they are written or looked up.

The word "subview" is part of the base name for at least two reasons:

1. The primary reason is that the base name should capture the method's
   core semantics, and adding a subview is semantically completely
   different from, say, adding a gesture recognizer.  They become parts
   of different logical collections on the view and come with utterly
   different side-effects.

2. It's important to have consistent and simple naming rules that work
   well for most APIs, and any rule we could think of that would lead us
   to breaking "add" from "subview" would either

   a) cause many APIs to become inarguably worse or
   b) neccessitate complicating the naming rules to avoid damaging those
      other APIs.

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

-- 
-Dave