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

[Michael Wells]

What is your evaluation of the proposal?

I’m a big fan of guidelines like these so count me as a strong +1.

In general

I’m supportive of lowerCamelCase for enumerations. 
I’m still not sure about the first argument label suggestions. Personally, I’d prefer that the first argument always include a label, but I know that is not a popular opinion.
I continue to believe that property access implies (or at least strongly hints) at O(1)

WRT translation from ObjC to Swift a few things come to mind:
Import things like[UIColor blueColor] to Swift as UIColor.blue instead of UIColor.blueColor(). That is, things that feel like static properties on a class should be imported that way. 
Are singleton accessors methods or properties? [NSNotificationCenter defaultCenter]imports as NSNotificationCenter.defaultCenter() or NSNotificationCenter.defaultCenter? 
Group string encoding constants (and other constants like this) together in an enum or struct. I can never remember NSUTF8StringEncoding since I’m always looking for StringEncoding first.
I know this is out of scope for this review, but I’d love for the guidelines to go even further in defining canonical Swift. What about, dare I say it, brace locations, tab-vs-spaces, how to wrap func definitions within some column width max, etc? From the sample code it appears that Apple has adopted a Swift style and it might be nice to make that public. This public style guide would not be a decree of "how one must write" Swift, but more as a "this is how the core team writes" Swift. I’m one of those developers that has no strong preference for these issues, but I really do value consistency.

Is the problem being addressed significant enough to warrant a change to Swift?

Most definitely.

Does this proposal fit well with the feel and direction of Swift?

Yes these guidelines makes a huge difference in how the language feels. It fits perfectly with the direction of Swift.

If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?

I've been a big proponent of design guides in all of the languages I’ve used: C, C++, Java, C#, Objective C, and now Swift. I really appreciate where languages make opinionated decisions on how to write idiomatic code.

How much effort did you put into your review? A glance, a quick reading, or an in-depth study?

I’ve read the proposals many times and I’ve been actively following this discussion.

> On Jan 31, 2016, at 9:29 PM, Ricardo Parada via swift-evolution <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. 
> 
> 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. 
> _______________________________________________
> 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/20160201/60074463/attachment.html>