[swift-evolution] [swift-evolution-announce] [Review] SE-0023 API Design Guidelines

[David Owens II]

> On Jan 23, 2016, at 11:53 AM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
> 
> 
> on Fri Jan 22 2016, David Owens II <swift-evolution at swift.org> wrote:
> 
>>> Be Grammatical
>>> 
>>> 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).
>> 
>> Is this guideline suggesting that we should design our APIs to
>> generally have both mutating and non-mutaging counterparts?
> 
> Definitely not.
> 
>> As other have pointed out, this is also very hard to do all the
>> time. I think the alternatives are worse. 
> 
> The alternatives to always creating mutating/nonmutating pairs?  What
> alternatives have you considered, and what do you see the consequences
> to be?
> 
>> It would be nice if there were a way to annotate all member functions
>> as mutating/non-mutating to really by-pass this ambiguity.
> 
> I don't know what you mean by that.  Can you explain?
> 
> FWIW, there are potential language-level approaches to this problem
> (e.g. https://github.com/apple/swift/blob/master/docs/proposals/Inplace.rst),
> but in the absence of language features, it's something we need a
> convention for.

Exactly. It seems like this convention is a work-around for a language design deficiency. In the case of value types, there are indeed other solutions that could even allow the same name for functions to be used for both mutating and non-mutating. The key thing of importance is bringing that clarity to the call site.

I think there are some interesting proposals in the link provided. Another potential:

var items = [...]
mut items.sort()            // sorts the items in-place
let copy = items.sort()     // sorts a copy of the items and returns that copy

let items = [...]
mut items.sort()            // error: unable to mutate a constant value

The other potential thing to look it is what it means for class-types to allow mutation. I simply cannot trust a class-type that has a function named with the correct guidelines or an "InPlace" suffix to actually return a real copy of the class type.

I guess my point is this: codifying a convention seems pre-mature as that convention doesn't bring the safety goals of the language into a place that's verifiable. All of the other guidelines are simply about clarity of use, this convention has a far reaching impact.

-David
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160124/3a0179f6/attachment.html>