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

Tue Feb 2 10:40:26 CST 2016

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)

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