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

Ricardo Parada rparada at mac.com
Tue Feb 2 15:02:05 CST 2016 

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

More information about the swift-evolution mailing list