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

Thorsten Seitz tseitz42 at icloud.com
Fri Feb 5 05:36:55 CST 2016 

+1 for keeping "union" 

When using "add" for mutating set union how would we express adding a single element?

Tossing about some ideas, where x is a single element and xs is a set and foo()/fooed() is the mutating/nonmutating pair for an operation:

Using addAll and removeAll for set operands:

- add(x)/adding(x), addAll(xs)/union(xs)
- remove(x)/removing(x), removeAll(xs)/removingAll(xs)
- intersect(xs)/intersection(xs)

or an alternative which keeps closer to set algebra:

- insert(x)/inserting(x), add(xs)/union(xs)
- remove(x)/removing(x), subtract(xs)/difference(xs)
- intersect(xs)/intersection(xs)

The latter one retains a verb/noun symmetry for the set algebra operations which I find quite nice.

-Thorsten 

> Am 02.02.2016 um 22:02 schrieb Ricardo Parada via swift-evolution <swift-evolution at swift.org>:
> 
> You can still have union() instead of or in addition to adding() and the API would still conform based on the following guideline:
> 
> Uses of nonmutating methods should read as noun phrases when possible, e.g. x.distanceTo(y), i.successor().
> 
> And union is the name of the operation, in other words, it is a noun. 
> 
> However the mutable method would have to be add() which I personally like since we are adding elements to the receiver. 
> 
> The subtract() / subtracting() could be called remove() / removing() so that it does not sound like an arithmetic operation. 
> 
> 
>> On Feb 2, 2016, at 11:59 AM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
>> 
>> 
>>> on Tue Feb 02 2016, Ricardo Parada <swift-evolution at swift.org> wrote:
>>> 
>>> Hi Dave,
>>> 
>>> Let me add the following to my ideas on union().  I actually reviewed
>>> SetAlgebra quickly and I think it could conform to the guidelines
>>> better if it used the following:
>>> 
>>> // Non-mutable methods
>>> let union = a.adding(b)                // returns a ∪ c
>>> let intersection = a.intersecting(b)        // returns a ∩ c
>>> let difference = a.subtracting(b)        // returns a - b
>>> let xor = a.xoring(b) // returns a △ b (a.k.a. "symmetric difference"
>>> or "exclusive or")
>>> 
>>> // Mutable methods (in-place)
>>> a.add(b)
>>> a.intersect(b)
>>> a.subtract(b)
>>> a.xor(b)
>> 
>> OK.  You may think this is just me, but a set abstraction that doesn't
>> include an operation called "union" is really hard for me to accept.
>> It's a basic part of the set abstraction.
>> 
>>> Thanks
>>> 
>>>> On Feb 1, 2016, at 11:58 PM, Ricardo Parada
>>>> <rparada at mac.com> wrote:
>>>> 
>>>> Thank you Dave for your feedback and questions. I hope I can answer
>>>> your questions satisfactorily. See below.
>>>> 
>>>> 
>>>> On Feb 1, 2016, at 7:30 PM, Dave Abrahams via swift-evolution
>>>> <swift-evolution at swift.org
>>>> <mailto:swift-evolution at swift.org>>
>>>> wrote:
>>>> 
>>>>> 
>>>>> Thanks for your review, Ricardo!  Just one question below.
>>>>> 
>>>>> on Sun Jan 31 2016, Ricardo Parada
>>>>> <swift-evolution at swift.org
>>>>> <mailto:swift-evolution at swift.org>>
>>>>> wrote:
>>>>> 
>>>>>> Proposal link:
>>>>>> 
>>>>>> https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md
>>>>>> <https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md>
>>>>>> 
>>>>>> What is your evaluation of the proposal?
>>>>>> +1
>>>>>> 
>>>>>> I read the guidelines and I like them a lot in general. I think
>>>>>> they are a very good start.
>>>>>> 
>>>>>> I have read the alternatives and disagreements in the discussion
>>>>>> threads.  However, in my opinion the guidelines still stand as the
>>>>>> winner. I find it better, simpler, more concise and better looking
>>>>>> than the alternatives discussed.
>>>>>> 
>>>>>> For example the ed/ ing ending for non-mutable methods. This is a
>>>>>> convention I have used in java for a long time and I found it very
>>>>>> natural in general even when the English language may not cooperate as
>>>>>> it has been discussed by others. I got used to this convention very
>>>>>> quickly many years ago in libraries I use in java.
>>>>> 
>>>>> What do you do about non-mutating versions of "split" and "union"
>>>>> under this pattern?
>>>> 
>>>> Even though the English language may not play nice with the
>>>> guideline in these scenarios, I do not think it is a big
>>>> problem. Let me answer to each individually.
>>>> 
>>>> split 
>>>> 
>>>> I think one can infer mutability by its usage on the call site. For
>>>> the example, if I read this code:
>>>> 
>>>> x.split()
>>>> 
>>>> I would infer that split() is mutating x. On the other hand if I read this:
>>>> 
>>>> let y = x.split(",")
>>>> 
>>>> I would infer that this split() method does not mutate x. This works
>>>> when reading code.
>>>> 
>>>> If on the other hand I am writing the code then I would probably
>>>> consult the documentation and learn whether it is mutating or not.
>>>> 
>>>> union 
>>>> 
>>>> It would be similar for union(). Now, let's say that you want to
>>>> have a mutable and non-mutable version of union() then we have to
>>>> look for a different name or perhaps look at other alternatives
>>>> mentioned.  I would consider first alternatives compatible with the
>>>> guidelines. For example add() and adding(). If you want to stick
>>>> with union as the name then look for other alternatives discussed
>>>> such as unionInPlace() and union().
>>>> 
>>>> The guidelines are not perfect but I think they are a good start. 
>>>> 
>>>> 
>>>>>> There is only one guideline that I think is not aligned with the
>>>>>> consensus I seem to pick up from the discussions. That is the use of
>>>>>> camel case for enum cases. After reading different opinions I am now
>>>>>> leaning towards saying that Enum cases should be lower camel case
>>>>>> given that they are values.  At first my opinion was the same as the
>>>>>> guideline. After reading the discussions and seeing examples I changed
>>>>>> my mind.
>>>>>> 
>>>>>> Is the problem being addressed significant enough to warrant a change to Swift?
>>>>>> This will bring a lot of changes when applied. I think they are a good
>>>>>> start. I don't think it should cover all cases.
>>>>>> 
>>>>>> I saw the loginWithUserName(_:password:) example and alternatives:
>>>>>> login(userName:password:), etc. I don't know if this is addressed in
>>>>>> the guidelines. I don't think this example falls under the weak type
>>>>>> first argument.  It would be nice to have some guidance here. I do not
>>>>>> know how to state it but I think in this case I would say
>>>>>> login(userName:password:) is better as it could be part of a family of
>>>>>> login() methods that take different parameters, i.e. credentials.
>>>>> 
>>>>> Then this is a second difference you have with the guidelines, as they
>>>>> are currently written to discourage first argument labels in almost all
>>>>> cases.
>>>> 
>>>> Thanks for pointing this out. I did not realize it until now. 
>>>> 
>>>> I'll have to think about this. 
>>>> 
>>>>>> Does this proposal fit well with the feel and direction of Swift?
>>>>>> Definitely. I find the guidelines are concise, natural and easy to get used to. 
>>>>>> 
>>>>>> If you have used other languages or libraries with a similar feature,
>>>>>> how do you feel that this proposal compares to those?
>>>>>> I have used Java libraries for many years that use the ed ending for
>>>>>> non-mutable methods for example.
>>>>>> 
>>>>>> How much effort did you put into your review? A glance, a quick
>>>>>> reading, or an in-depth study?
>>>>>> I read the proposal entirely and I have read the majority of
>>>>>> responses in the mailing list.
>>>>>> _______________________________________________
>>>>>> 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>
>>>>> 
>>>>> -- 
>>>>> -Dave
>>>>> 
>>>>> _______________________________________________
>>>>> 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>
>>> _______________________________________________
>>> swift-evolution mailing list
>>> swift-evolution at swift.org
>>> https://lists.swift.org/mailman/listinfo/swift-evolution
>> 
>> -- 
>> -Dave
>> 
>> _______________________________________________
>> swift-evolution mailing list
>> swift-evolution at swift.org
>> https://lists.swift.org/mailman/listinfo/swift-evolution
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160205/b492f5dc/attachment.html>

More information about the swift-evolution mailing list