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

[Dave Abrahams]

Thanks for your review, Michael!

A couple of questions below

on Mon Feb 01 2016, Michael Wells <swift-evolution at swift.org> wrote:

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

What would you use for a label here, and why?

  someSet.remove(someElement)

> I continue to believe that property access implies (or at least
> strongly hints) at O(1)

+1. For the record, I think the strongest expression of this fact
we're going to be able to get approved is already in the guidelines:
"document the complexity of any computed property that is not O(1)"

> WRT translation from ObjC to Swift a few things come to mind:

Would you mind posting these thoughts in the review thread of SE-0005?

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

I can imagine we'd address these kinds of things in later review cycles.
Regardless, I think we probably need a separate set of guidelines for
standard library code, just to cover some of the conventions we use
there but don't expect to impose on everyone else.  That could serve as
your guide to the core team's practices.

> 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
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

-- 
-Dave