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

[Dave Abrahams]

on Sat Jan 23 2016, Erica Sadun <swift-evolution at swift.org> wrote:

>> On Jan 23, 2016, at 11:51 AM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
>> 
>> 
>> on Fri Jan 22 2016, Erica Sadun <swift-evolution at swift.org> wrote:
>> 
>
>>>> On Jan 22, 2016, at 4:24 PM, Dave Abrahams via swift-evolution
>>>> <swift-evolution at swift.org> wrote:
>>>> 
>>>> 
>>>> on Fri Jan 22 2016, Erica Sadun
>>> 
>>>> <swift-evolution at swift.org
>>>> <mailto:swift-evolution at swift.org>>
>>>> wrote:
>>>> 
>>>>> _______________________________________________ swift-evolution mailing list swift-evolution at swift.org <mailto:swift-evolution at swift.org> 
>>>>> https://lists.swift.org/mailman/listinfo/swift-evolution <https://lists.swift.org/mailman/listinfo/swift-evolution>
>>>>> 
>>>>> Current:
>>>>> 
>>>>> * Use imperative verb phrases for mutating methods: x.reverse(), x.sort(), x.tweak()
>>>>> * Use noun phrases for non-mutating methods: x.distanceTo(...), idx.successor()
>>>>> 
>>>>> Proposed:
>>>>> 
>>>>> * Use verb phrases to declare procedural methods, whether or not they mutate an instance or just produce side
>>>>>   effects: x.reverse(), x.sort(), x.tweak(), x.perform(), x.dispatch(), x.send()
>>>>> * Use noun phrases to describe values returned by a functional method: x.distanceTo(y), index.successor() (This
>>>>>   admittedly leaves further issues around other functional methods, for example, seq.separatedBySequence(seq) and
>>>>>    int.strideTo(other: Self, step:Self.Stride), etc. )
>>>>> 
>>>>> I suggest that mutating methods are just a procedural method (side effect, no return value) vs functional.
>>>> 
>>>> Hi Erica,
>>>> 
>>>> When you propose a change, could you please explain why you think your
>>>> change is an improvement?  
>>>> 
>>>> Thanks,
>>>> Dave
>>> 
>>> I believe the current distinction is misguided in focusing on mutating and non-mutating implementations when the
>>> differentiation can be viewed from a more general level. There are two ways to distinguish these:
>>> 
>>> * Does this method or function have side effects (which is what the current API approach intends to address); and
>>> * Is this method or function inherently functional or procedural in
>>> nature, returning a value or not.
>> 
>> Okay, I understand what you're driving at, but these don't seem to be
>> separate distinctions.  Can you show me a method that's inherently
>> functional but has side effects, or inherently procedural but has none?
>
> func loginWithCredential(credential: SomeCredentialType) -> SuccessTokenType? {...}
> func printThisValueNicelyFormatted<T>(something: T) {...}

Which one of these would you say is "inherently functional?"  They both
just look like methods with side-effects that would demand a verb phrase
according to your first criterion about side-effects.  Why introduce the
"functional/procedural" distinction?

>>> For example, contrast sort() and sortInPlace().  Even with the current
>>> approach they lack a natural clarity. You could easily swap
>>> them without anything "breaking" in understanding because your
>>> solution is conventional, not based on any underlying principle.
>> 
>> There's certainly an underlying principle there: that methods that
>> mutate the receiver, and have a nonmutating counterpart that instead
>> returns a modified *copy* of the receiver, are named with "InPlace"
>> suffix.  It's not as general as what you're suggesting, but it's
>> something.
>> 
>> How could one could ever call a nonmutating method that returns a new
>> collection "sortInPlace," without causing confusion?  How would people
>> interpret "InPlace" as conveying meaningful information?
>
> I could imagine two algorithms, one that limits excess memory by
> sorting in place, and another that uses sort-and-copy-back, so the
> sort is not done in place. 

Yeah, but we don't name things according to their implementation
details, we name them according to their semantics.

> My point is not that this is ideal naming but that I was addressing
> the example that was part of the original.

Sorry, I don't understand what you mean here.  If I'm just being too
dense to deal with, please feel free to declare my understanding of this
sentence inessential. :-)

>> With noun/verb naming, the function name reflects the
>> functional/procedural underlying differentiation. 
>>
>>> * A function produces something: f(x) -> y. 
>>> * A procedure does something: g(x) -> Void
>>> 
>>> Under my proposed change, the procedural variation would be sort,
>>> sortInPlace, etc. Optional adverbs and near-adverbs
>>> could distinguish similar versions sortQuickly, sortBalanced, etc.
>>> 
>>> The functional would be sortedVersion or with a slight rule tweak that
>>> infers the subject of the action, sorted. 
>> 
>> Two issues with "sortedVersion":
>> 
>> 1. "Version" is needless for readability.  "Return the list of names,
>>   sorted."
>
> I included this to force it to be a noun because I was trying to keep with the
> examples used in the original. 

Which original and which examples?  I'm sure these questions are
frustrating, but I am trying and I truly don't get it...

Sorry,

-- 
-Dave