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

[Dave Abrahams]

on Sun Jan 24 2016, David Owens II <swift-evolution at swift.org> wrote:

>> 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'd love to discuss langauge features for handling this, but let's take
all of that into a separate thread, please.

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

Sorry, could you clarify what you mean by "bring the safety goals of the
language into a place that's verifiable" and clarify why having a "far
reaching impact" would somehow conflict with being "about clarity of use?"

It seems to me that this convention is about how to express whether a
method is going to mutate so it's clear at the use-site.  What am I
missing?

-- 
-Dave