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

[Jacob Bandes-Storch]

Proposal link:
https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md

> What is your evaluation of the proposal?

I think there are more things which would make a "guidelines" document even
better for promoting consistent code:

- When to use functions vs. properties for getters. The changes in SE-0006
<https://github.com/apple/swift-evolution/blob/master/proposals/0006-apply-api-guidelines-to-the-standard-library.md>
include
"func min()" and "var underestimatedCount". SE-0005
<https://github.com/apple/swift-evolution/blob/master/proposals/0005-objective-c-name-translation.md>
includes "class func darkGray()". I imagine it should be implied that
properties are more efficient to compute, but this doesn't seem to be
applied consistently.

- Edge cases of naming, such as what to do with acronyms (like URL) when
they appear in function and variable names, especially at the beginning.

- When to use structs/classes/enums; when to use optionals; other such
basic API design topics.

While certainly not everything from the Coding Guidelines for Cocoa
<https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/CodingGuidelines/CodingGuidelines.html>
(linked from SE-0005) applies to Swift, the Swift guidelines would do well
to match its thoroughness.


    Protocols that describe what something is should read as nouns (e.g.
Collection).
    Protocols that describe a capability should be named using the suffixes
able, ible, or ing (e.g. Equatable, ProgressReporting).

"SetAlgebra" (from SE-0006) doesn't really fit in with this.


Extremely minor:
    text = "The value is: "
    text += String(veryLargeNumber)
    text += " and in hexadecimal, it's"
    text += String(veryLargeNumber, radix: 16)

The second string literal should have a space at the end as well as the
beginning.


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

Having a set of guidelines is important.


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

Yes.


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

Fairly in-depth.

Jacob

On Fri, Jan 22, 2016 at 1: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
>
> 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
>
> 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
>
> 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
>
> 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/20160123/dca5fa86/attachment.html>