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

[Dave Abrahams]

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

>> On Jan 23, 2016, at 10:39 PM, Douglas Gregor <dgregor at apple.com> wrote:
>> 
>>> 
>>> On Jan 22, 2016, at 9:34 PM, Charles Kissinger
>>> <crk at akkyra.com
>
>>> <mailto:crk at akkyra.com>> wrote:
>>> 
>>>> 
>>>> On Jan 22, 2016, at 3:59 PM, Trent Nadeau via swift-evolution
>>>> <swift-evolution at swift.org
>>>> <mailto: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()
>> 
>> Interesting. For me, it feels like the acronym should should up in
>> ALLCAPS or nocaps; never with just a Leadingcap. For example:
>> 
>> 	var htmlElement = HTMLElement()
>> 
>
> I guess I just don’t like my function calls SHOUTing at me. :-)
>
> The leading-caps-for-acronyms style might not be particularly
> popular. The most prominent use I’m aware of is in the .NET
> frameworks.

Peeple, please.  Not to pick nits, but these are *initialisms*, not
*acronyms*
(http://www.dailywritingtips.com/initialisms-and-acronyms/). The
difference matters, because there's a very good argument for using
different conventions for the two, i.e. Nasa and Radar (acronyms) read
fine while Html and Fbi and Cia (initialisms) ... don't.

-- 
-Dave