[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?

Not everyone will agree, but IMO *initialisms* should be uniformly upper-
or lower-cased according to the other conventions.  So if it's a type,
HTMLElement, and if it's a property, htmlElement.

My rationale is that, in general, when these words are mixed-case they
tend to look like things one can't pronounce.  I'm used to seeing both
of these:

     HTML
     html

and reading them accordingly, but

     Html

is not a common presentation for this initialism.  Like PHP, php, Php.
The first two work, the latter looks like a broken doctorate degree!

When it comes to *acronyms*, like RADAR, or LASER, I think the argument
for uniformity is a lot weaker; we commonly see it written as "Radar,"
and the inclination given by the initial capital to mentally read it the
way it is spelled (rather than mentally name each letter) is not harmful
in this case... because that's how acronyms are pronounced.  In these
cases, I think it would be much better to make them look like everything
else, lower- or upper-camel-cased according to the conventions for types
and values.

Whatever we choose to do, I think it's important that values start with
a lower-case letter.

> 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()
>
> --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