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

[Ricardo Parada]

Proposal link:

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. 

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. 

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