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

[Dave Abrahams]

on Fri Jan 22 2016, Charles Kissinger <swift-evolution at swift.org> wrote:

>> On Jan 22, 2016, at 3:59 PM, Trent Nadeau via swift-evolution
>> <swift-evolution at swift.org> wrote:
>> 
>> Under "Follow case conventions", how should acronyms (like "HTML") be handled: HTMLElement or HtmlElement?
>
> I would certainly prefer the second style. Unless the acronym comes at
> the end of the identifier, it is more readable when only the first
> letter of the acronym is uppercase, IMO. Otherwise the acronym merges
> with the capitalized first letter of the following word.
>
> Using all caps for acronyms also doesn’t work very well at the start of a variable name, leading to:
>
> var hTMLElement = HTMLElement()
>
> versus:
>
> var htmlElement = HtmlElement()

One of the big internal debates here, regarding these, has been about
whether they should follow the other case conventions.  The Objective-C
style has been to uppercase initialisms even in places where the
conventions would otherwise prescribe lower case, e.g.:

  var HTMLElement = ...

vs

  car htmlElement = ...

In my personal opinion, keeping the initialism all upper case is not
worth undermining the visual clue we get from the case conventions about
what is a type.  But that's just me...

> --CK
>
>> On Fri, Jan 22, 2016 at 4:02 PM, Douglas Gregor via swift-evolution
>> <swift-evolution at swift.org
>> <mailto: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
>> <mailto:swift-evolution at swift.org>
>> https://lists.swift.org/mailman/listinfo/swift-evolution <https://lists.swift.org/mailman/listinfo/swift-evolution>
>> 
>> 
>> 
>> 
>> -- 
>> Trent Nadeau
>> _______________________________________________
>> swift-evolution mailing list
>> swift-evolution at swift.org
>> https://lists.swift.org/mailman/listinfo/swift-evolution
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

-- 
-Dave