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

[Dave Abrahams]

on Sat Jan 23 2016, Jacob Bandes-Storch <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?
>
> 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.

Separately replied to the above, continuing with the rest

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

This is something that was still under discussion internally when the
review started.  The argument internally has been between whether to:

1. Always capitalize the whole initialism, even in variable and method
   names.
2. Capitalize or lowercase the whole initialism according to case
   conventions (e.g. in a type name it would be all-caps).

Some people in this group have expressed a strong preference for another
possibility, which IIUC is “All but the first letter of the initialism
are lower-case; capitalize according to case conventions,
i.e. no-special-treatment."

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

Hmm, I'm not sure whether that's in scope for this document.

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

When I look at that document, the section titles at least imply it's
*only* about naming and not about any of those other things you just
mentioned.

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

It arguably fits in with the former, but I agree it's not a perfect
fit.  If you have better suggestions, I'm all ears.

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

Thanks!

-- 
-Dave