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

[Erica Sadun]

It suddenly occurs to me it's almost the 31st and I haven't actually responded to the proposal as a proposal. I heartily endorse a general set of API guidelines and I appreciate this first approach towards satisfying that goal. I have issues with two sections.

First, I'd entirely eliminate the guidance in the "Be Grammatical" section and move the section with boolean assertions and property names to Special Instructions.

* I disagree with the mutating/non-mutating differentiation. I started writing about this here before personally abandoning it as too big a question: Grammatical.md <https://github.com/erica/SwiftStyle/blob/master/Grammatical.md>. In a nutshell, side-effects and pure functionality are not considered the way I'd want them to be and the ed/ing naming is problematic.
* The protocol question is big and wide as well, and I have written on-list: it's not "the role of a protocol to describe implementation details...Going that way leads you to over-designated hungarian-esque guidelines that I'd rather keep loose, friendly, and sensible."

In "Conventions":

* I don't like endorsing that any property could or should not be O(1) (vs recommending using a function instead)
* The case convention for enumerations remains conventional without a guiding principle. I'd rather have a firm "use lower camel case for members" that I can complain about  (because it feels to me like "pick a type layout for this memory", so upper camel) rather than "use upper camel and let everyone on the Swift team complain about it" once and for all.
* With regard to argument labels, I'd like to add two rules, as detailed in-thread and written about here: ArgumentLabels.md <https://github.com/erica/SwiftStyle/blob/master/ArgumentLabels.md>

Differentiate related calls whose implementations are distinguished by their parameters, as you would with initializers, using first parameter labels. Instead of loginWithUserName("blah", password: "...") and loginWithCredential(myCredential), prefer:

login(userName: "blah", password: "...")
login(credential: myCredential)
This approach emphasizes the action being taken (login) and demotes the actual arguments involved in performing that action. In doing so, they require labels to differentiate which implementation of that action is to be used.

and

Prefer external names for the first parameter when the natural semantic relationship between the parameters is stronger than their relation to the operation. 

For example, the following calls use labels for the first parameter:

login(userName: "blah", password: "...")
moveTo(x: 50.0, y: 30.0)
constructColor(red: 0.2, green: 0.3, blue: 0.1)
This example is contrary to Swift's normal naming scheme which integrates the first argument into the function or method name, for example:

loginWithUserName("blah", password: "...")
moveToX(50.0, y: 30.0)
constructColorWithRed(0.2, green: 0.3, blue: 0.1)
The relationships between (x, y), (username, password), and (red, green, blue) are strong enough to allow you to make a judgement call to employ an external label.

The following shows a counter-example.

addLineTo(p1, withWidth: 25.0)
In this call, the point and width have no natural relationship. There's no reason to create an external label for the first argument so this example follows the standard Swift call approach.


> On Jan 22, 2016, at 2:02 PM, Douglas Gregor via swift-evolution <swift-evolution at swift.org> wrote:
> 
> Hello Swift community,
> 
> The review of SE-0023"API Design Guidelines" begins now and runs through January 31, 2016. The proposal is available here:
> 
> 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>
> Reviews are an important part of the Swift evolution process. All reviews should be sent to the swift-evolution mailing list at
> 
> https://lists.swift.org/mailman/listinfo/swift-evolution <https://lists.swift.org/mailman/listinfo/swift-evolution>
> or, if you would like to keep your feedback private, directly to the review manager. When replying, please try to keep the proposal link at the top of the message:
> 
> 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>
> Reply text
> 
> Other replies
>  <https://github.com/apple/swift-evolution#what-goes-into-a-review-1>What goes into a review?
> 
> The goal of the review process is to improve the proposal under review through constructive criticism and, eventually, determine the direction of Swift. When writing your review, here are some questions you might want to answer in your review:
> 
> What is your evaluation of the proposal?
> Is the problem being addressed significant enough to warrant a change to Swift?
> Does this proposal fit well with the feel and 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?
> How much effort did you put into your review? A glance, a quick reading, or an in-depth study?
> More information about the Swift evolution process is available at
> 
> https://github.com/apple/swift-evolution/blob/master/process.md <https://github.com/apple/swift-evolution/blob/master/process.md>
> Thank you,
> 
> -Doug Gregor
> 
> Review Manager
> 
> _______________________________________________
> 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/20160129/81461dfc/attachment.html>