[swift-evolution] Proposal: Update the API Design Guidelines to reflect current Standard Library method naming conventions

[Daniel Steinberg]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20151206/7b277522/attachment.html>