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

[Dave Abrahams]

Thanks for your review, Ricardo!  Just one question below.

on Sun Jan 31 2016, Ricardo Parada <swift-evolution at swift.org> wrote:

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

What do you do about non-mutating versions of "split" and "union" under
this pattern?

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

> 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

-- 
-Dave