[Discussion] API Guidelines


(Charlie Monroe) #1

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


(Zachary Waldowski) #2

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@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@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Adrian Zubarev) #3

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
zach@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@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 Abrahams) #4

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.

···

on Fri Oct 14 2016, Zach Waldowski <swift-evolution@swift.org> wrote:

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@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@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


(William Sumner) #5

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

···

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


(Tony Parker) #6

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


(Dave Abrahams) #7

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.

···

on Fri Oct 14 2016, Adrian Zubarev <swift-evolution@swift.org> wrote:

// 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
zach@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@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


(Dave Abrahams) #8

Actually, by itself that rule would allow

   self.view.add(someOtherView)

But we don't do that because views aren't collections; they *have*
collections.

···

on Fri Oct 14 2016, William Sumner <swift-evolution@swift.org> wrote:

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

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

--
-Dave


(Charlie Monroe) #9

Thanks, Dave and Tony, it really helped.

···

On Oct 16, 2016, at 9:55 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

on Fri Oct 14 2016, Adrian Zubarev <swift-evolution@swift.org <mailto:swift-evolution@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@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@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@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 <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution