Re: [swift-evolution] [Discussion] API Guidelines

[Charlie Monroe via swift-evolution]

Thanks, Dave and Tony, it really helped.



> On Oct 16, 2016, at 9:55 PM, Dave Abrahams via swift-evolution 
>  wrote:
> 
> 
> on Fri Oct 14 2016, Adrian Zubarev  > 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@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,
>>> with newElements: String)
>>> 
>>> instead of
>>> 
>>> public mutating func replace(subrange bounds: ClosedRange,
>>> 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
>> https://lists.swift.org/mailman/listinfo/swift-evolution
>> 
> 
> -- 
> -Dave
> 
> ___
> swift-evolution mailing list
> swift-evolution@swift.org 

Re: [swift-evolution] [Discussion] API Guidelines

[Dave Abrahams via swift-evolution]

on Fri Oct 14 2016, Adrian Zubarev  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@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,
>> with newElements: String)
>>  
>> instead of
>>  
>> public mutating func replace(subrange bounds: ClosedRange,
>> 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
> https://lists.swift.org/mailman/listinfo/swift-evolution
>

-- 
-Dave

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

Re: [swift-evolution] [Discussion] API Guidelines

[Dave Abrahams via swift-evolution]

on Fri Oct 14 2016, Zach Waldowski  wrote:

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

That's because there's a distinction between appending the newElements
paramter (as a single new element on an array of Any) and appending its
elements.

> But there is ambiguity asking URL to "give me a new URL by
> appending". Appending what?

Actually, no, you are passing an argument.  That's what's being
appended.  If there's only one reasonable way to append a String to a
URL, no noun should be needed.  If there's some ambiguity as to the
semantics, that might justify the "pathComponent:" label.

> 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,
>> with newElements: String)
>> 
>> instead of
>> 
>> public mutating func replace(subrange bounds: ClosedRange,
>> 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

-- 
-Dave

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

Re: [swift-evolution] [Discussion] API Guidelines

[Tony Parker via swift-evolution]

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), 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 
>  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 ) 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,
>> > with newElements: String)
>> > 
>> > instead of
>> > 
>> > public mutating func replace(subrange bounds: ClosedRange,
>> > 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
> 
> 
> 

Re: [swift-evolution] [Discussion] API Guidelines

[William Sumner via swift-evolution]

> On Oct 14, 2016, at 8:49 AM, Adrian Zubarev via swift-evolution 
>  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

This conforms to the following rule from the Argument Labels section of the 
naming guidelines:

“[I]f the first argument forms part of a grammatical phrase, omit its label, 
appending any preceding words to the base name, e.g. x.addSubview(y)"

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

Re: [swift-evolution] [Discussion] API Guidelines

[Adrian Zubarev via swift-evolution]

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) 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,
> with newElements: String)
>  
> instead of
>  
> public mutating func replace(subrange bounds: ClosedRange,
> 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
https://lists.swift.org/mailman/listinfo/swift-evolution

Re: [swift-evolution] [Discussion] API Guidelines

[Zach Waldowski via swift-evolution]

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,
> with newElements: String)
> 
> instead of
> 
> public mutating func replace(subrange bounds: ClosedRange,
> 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] [Discussion] API Guidelines

[Charlie Monroe via swift-evolution]

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, with 
newElements: String)

instead of

public mutating func replace(subrange bounds: ClosedRange, 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