[swift-evolution] [Review] SE-0023 API Design Guidelines
dabrahams at apple.com
Wed Jan 27 13:42:56 CST 2016
on Sat Jan 23 2016, Jacob Bandes-Storch <swift-evolution at swift.org> wrote:
> Proposal link:
>> What is your evaluation of the proposal?
> I think there are more things which would make a "guidelines" document
> better for promoting consistent code:
> - When to use functions vs. properties for getters. The changes in
> "func min()" and "var underestimatedCount". SE-0005
> 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
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
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,
> - 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
> (linked from SE-0005) applies to Swift, the Swift guidelines would do
> 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
> Protocols that describe what something is should read as nouns
> Protocols that describe a capability should be named using the
> 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
More information about the swift-evolution