Proposal: Update the API Design Guidelines to reflect current Standard Library method naming conventions


(Daniel Steinberg) #1

I love that the team has released API Design Guidelines and find them very helpful. One piece of advice, however, seems to be at odds with current Standard Library practice.

Currently the methods sort() and sortInPlace() are the non-mutating and mutating versions of sorting a collection. Similarly, there are pairs of methods in Set named union() and unionInPlace(), intersect() and intersectInPlace() and so on.

I think the x(), xInPlace() pairs are easier to use than the previous pairs. the inPlace variant is clearly the mutating implementation as the name tells me that the operation is going to be performed in place on the reciever.

Previously the sort methods were named sort() and sorted(). I never could remember which is which. The API Guidelines currently recommend this sort/sorted practice as opposed to sort/sortInPlace.

I know this is a small issue - given the many important tasks you have before you, but I’d love to see the section “Be Grammatical” revised to update the following advice to match current practice. The following two are not consistent with library practices.

Uses of mutating methods should read as imperative verb phrases, e.g., x.reverse(), x.sort(), x.append(y).

and

When a mutating method is described by a verb, name its non-mutating counterpart according to the “ed/ing” rule, e.g. the non-mutating versions of x.sort() and x.append(y) are x.sorted() and x.appending(y).

The Swift Programming Language Guide 2.1 reflects the actual use of sort()

For example, the Swift standard library provides both the mutating method sortInPlace() and the nonmutating method sort() to collections whose generator element conforms to the Comparableprotocol.

Note that in the API Guidelines sort() should be mutating and in actuality (and in the Language Guide) sort() is non-mutating.

Thank you,

Daniel


(Chris Lattner) #2

Hi Daniel,

This is a known issue, and it is because we want to keep Swift 2.2 reasonable source compatible with Swift 2. The changes to the standard library will land after Swift 2.2 branches for its release in the spring.

If you’re interested in more details on this effort, check out this blog post:

It includes a link to the diff-in-progress for the standard library.

-Chris

···

On Dec 6, 2015, at 6:40 AM, Daniel Steinberg via swift-evolution <swift-evolution@swift.org> wrote:

I love that the team has released API Design Guidelines and find them very helpful. One piece of advice, however, seems to be at odds with current Standard Library practice.

Currently the methods sort() and sortInPlace() are the non-mutating and mutating versions of sorting a collection. Similarly, there are pairs of methods in Set named union() and unionInPlace(), intersect() and intersectInPlace() and so on.


(Dmitri Gribenko) #3

I love that the team has released API Design Guidelines and find them very
helpful. One piece of advice, however, seems to be at odds with current
Standard Library practice.

Currently the methods sort() and sortInPlace() are the non-mutating and
mutating versions of sorting a collection. Similarly, there are pairs of
methods in Set named union() and unionInPlace(), intersect() and
intersectInPlace() and so on.

Hi Daniel,

This is a known issue, and it is because we want to keep Swift 2.2
reasonable source compatible with Swift 2. The changes to the standard
library will land after Swift 2.2 branches for its release in the spring.

If you’re interested in more details on this effort, check out this blog
post:
https://swift.org/blog/swift-3-api-design/

It includes a link to the diff-in-progress for the standard library.

Hi Chris,

I think Daniel is not highlighting the inconsistency, but saying that he
likes ~InPlace better:

···

On Sun, Dec 6, 2015 at 3:03 PM, Chris Lattner via swift-evolution < swift-evolution@swift.org> wrote:

On Dec 6, 2015, at 6:40 AM, Daniel Steinberg via swift-evolution < > swift-evolution@swift.org> wrote:

On Dec 6, 2015, at 6:40 AM, Daniel Steinberg via swift-evolution < swift-evolution@swift.org> wrote:

Previously the sort methods were named sort() and sorted(). I never could

remember which is which.

Dmitri

--
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr@gmail.com>*/


(Daniel Steinberg) #4

Thank you

···

On Dec 6, 2015, at 6:03 PM, Chris Lattner <clattner@apple.com> wrote:

On Dec 6, 2015, at 6:40 AM, Daniel Steinberg via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

I love that the team has released API Design Guidelines and find them very helpful. One piece of advice, however, seems to be at odds with current Standard Library practice.

Currently the methods sort() and sortInPlace() are the non-mutating and mutating versions of sorting a collection. Similarly, there are pairs of methods in Set named union() and unionInPlace(), intersect() and intersectInPlace() and so on.

Hi Daniel,

This is a known issue, and it is because we want to keep Swift 2.2 reasonable source compatible with Swift 2. The changes to the standard library will land after Swift 2.2 branches for its release in the spring.

If you’re interested in more details on this effort, check out this blog post:
https://swift.org/blog/swift-3-api-design/

It includes a link to the diff-in-progress for the standard library.

-Chris


(Chris Lattner) #5

Ah, sorry for the misunderstanding!

-Chris

···

On Dec 6, 2015, at 3:10 PM, Dmitri Gribenko <gribozavr@gmail.com> wrote:

On Sun, Dec 6, 2015 at 3:03 PM, Chris Lattner via swift-evolution <swift-evolution@swift.org> wrote:

On Dec 6, 2015, at 6:40 AM, Daniel Steinberg via swift-evolution <swift-evolution@swift.org> wrote:

I love that the team has released API Design Guidelines and find them very helpful. One piece of advice, however, seems to be at odds with current Standard Library practice.

Currently the methods sort() and sortInPlace() are the non-mutating and mutating versions of sorting a collection. Similarly, there are pairs of methods in Set named union() and unionInPlace(), intersect() and intersectInPlace() and so on.

Hi Daniel,

This is a known issue, and it is because we want to keep Swift 2.2 reasonable source compatible with Swift 2. The changes to the standard library will land after Swift 2.2 branches for its release in the spring.

If you’re interested in more details on this effort, check out this blog post:
https://swift.org/blog/swift-3-api-design/

It includes a link to the diff-in-progress for the standard library.

Hi Chris,

I think Daniel is not highlighting the inconsistency, but saying that he likes ~InPlace better:

On Dec 6, 2015, at 6:40 AM, Daniel Steinberg via swift-evolution <swift-evolution@swift.org> wrote:
> Previously the sort methods were named sort() and sorted(). I never could remember which is which.

Dmitri

--
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr@gmail.com>*/


(Daniel Steinberg) #6

Yes

···

On Dec 6, 2015, at 6:10 PM, Dmitri Gribenko <gribozavr@gmail.com> wrote:

On Sun, Dec 6, 2015 at 3:03 PM, Chris Lattner via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

On Dec 6, 2015, at 6:40 AM, Daniel Steinberg via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

I love that the team has released API Design Guidelines and find them very helpful. One piece of advice, however, seems to be at odds with current Standard Library practice.

Currently the methods sort() and sortInPlace() are the non-mutating and mutating versions of sorting a collection. Similarly, there are pairs of methods in Set named union() and unionInPlace(), intersect() and intersectInPlace() and so on.

Hi Daniel,

This is a known issue, and it is because we want to keep Swift 2.2 reasonable source compatible with Swift 2. The changes to the standard library will land after Swift 2.2 branches for its release in the spring.

If you’re interested in more details on this effort, check out this blog post:
https://swift.org/blog/swift-3-api-design/

It includes a link to the diff-in-progress for the standard library.

Hi Chris,

I think Daniel is not highlighting the inconsistency, but saying that he likes ~InPlace better:

On Dec 6, 2015, at 6:40 AM, Daniel Steinberg via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:
> Previously the sort methods were named sort() and sorted(). I never could remember which is which.

Dmitri

--
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr@gmail.com <mailto:gribozavr@gmail.com>>*/