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

Dave Abrahams dabrahams at apple.com
Fri Feb 5 13:21:58 CST 2016 

on Fri Feb 05 2016, Haravikk <swift-evolution at swift.org> wrote:

> Actually the same method name add can be applied to both single and
> multiple elements, since it should be impossible for Element to be a
> sequence of itself the following should never be ambiguous:
>
> 	func add(_ element:Element)
> 	func add<S:SequenceType where S.Generator.Element = Element)(_ elementsOf:S)
>
> So there’s actually no need for a second name. Personally it’s a bug
> bear of mine about Arrays with their append() and appendContentsOf()
> methods; both are append actions, the only difference is what you’re
> appending. 

It becomes ambiguous/confusing when you have 

   var a: [Any] = []
   a.add(a)

even if the compiler picks one of these reliably, it's not obvious which
semantics you're getting at the call site. 

> If clarity is an issue then the external label could be required in
> the sequence case but personally I don’t think it requires the extra
> clarity as long as you know what you’re passing into the method.
>
> Using your terminology I’d therefore just stick to add/union,
> remove/removing and intersect/intersection, i.e- no special cases for
> xs.
>
>> On 5 Feb 2016, at 11:36, Thorsten Seitz via swift-evolution
>> <swift-evolution at swift.org> wrote:
>> 
>> +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
>> <mailto: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
>>> <mailto:swift-evolution at swift.org>>
>>> wrote:
>>> 
>>>> 
>>>> on Tue Feb 02 2016, Ricardo Parada
>>>> <swift-evolution at swift.org
>>>> <mailto: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
>>>>>> <mailto: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>
>>>>>> <mailto: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>
>>>>>>> <mailto: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>
>>>>>>>> <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>
>>>>>>>> <mailto: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>
>>>>>>>> <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>
>>>>>>> <mailto: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>
>>>>>>> <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
>>>>> <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
>>> <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
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

-- 
-Dave

More information about the swift-evolution mailing list