[swift-evolution] [Discussion] API Guidelines

[Charlie Monroe]

Thanks, Dave and Tony, it really helped.



> On Oct 16, 2016, at 9:55 PM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
> 
> 
> on Fri Oct 14 2016, Adrian Zubarev <swift-evolution at swift.org <mailto: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
> 
> _______________________________________________
> 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/20161018/aa240d02/attachment.html>