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

Tue Feb 2 10:59:58 CST 2016

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