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

Haravikk swift-evolution at haravikk.me
Fri Feb 5 10:10:19 CST 2016 

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. 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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160205/20140a59/attachment.html>

More information about the swift-evolution mailing list