Analysis of case conventions for initialisms

Evolution Discussion
21

Strong dislike for #2. I understand and accept the benefits, but I
just don’t like how that looks.

I also don’t use #1 or #3. Instead, initialisms in my code are always
all uppercase, no exceptions.

For type names, I can’t remember a case in my code where that could
not be avoided or was too bad to read.
For local variables, methods, and functions, I try to find a name that
puts the initialism at the end of the name, e.g. let publicationURL =
document.URLForPublication

Interesting approach. If you'd like to create an amended document that
accounts for that one, too, I'd be happy to incorporate it. However,
note that I've tried pretty hard to stay away from subjective factors in
the analysis; it would be good if you could do the same.

A separate poll on the violence of peoples' negative reaction to each
choice might not be a bad idea—that stuff counts, too, as long as more
than a handful of people respond.

···

on Fri Feb 12 2016, Marco Masser <swift-evolution@swift.org> wrote:

In my experience, my guidelines don’t always work. Just like everyone else’s.

On 2016-02-12, at 06:51, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

I just posted a write-up about various case conventions for initialisms:
https://gist.github.com/dabrahams/55fc5ece355da4664730\. I was surprised
at how it turned out, FWIW.

Cheers,

--
-Dave

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave

22

(Warning: I'm going to use "acronym" loosely. Sorry.)

Strong dislike for #2. I understand and accept the benefits, but I

just don’t like how that looks.

Me too. I look at the examples and I'm frankly just revolted. It's a
visceral reaction, something I have trouble analyzing because it's so
violent. Whatever the practical benefits, it reads like a deliberate
abuse of the language, like someone choosing expedience over good
style, lyk sum1 doin dis bcuz its so hard 2 pres da btns.

But emotional reactions are hard to convey convincingly in text, so
I'll try to distill some of it into logical argument.

Some acronym-using terms, like "XML document", are easy to turn into
identifiers; others, like "AWS S3 RPC URL"*, are difficult. Option #2
handles this problem by making all acronyms equally ugly and
unreadable. I don't think that's an improvement.

I especially think it's not an improvement because the resulting
identifiers are so hard to read. It's true that `AwsS3RpcUrl` is
technically *parseable* since the word boundaries are demarcated
(well, except for that pesky `3`), but is it actually *readable* when
you set eyes on it? It's not for me. My brain, being used to English,
tries to read those uppercase-lowercase combinations as actual words
with actual pronunciations and it just sees gibberish.

Yes, the analysis tries to account for that factor with the bullet
entitled “encourages spelling rather than pronouncing”

Maybe that would get better with time, but this is something that
every new Swift developer would go through.

This is clearly highly subjective. Some people have no problem with it.

Capitalizing acronyms may be ambiguous sometimes, but it at least
ensures that you never misread an acronym as a word.

And for those pathological cases where we think there's too much
ambiguity, we *do* have another option: `AWS_S3_RPC_URL`. Swift style
disfavors underscores, but it disfavors lack of clarity even more. To
me, `AWS_S3_RPC_URL` is *far* clearer than either `AWSS3RPCURL` *or*
`AwsS3RpcUrl`.

Incidentally, how common *are* concatenated acronyms or other forms of
acronym-related ambiguity? And when it does happen in existing
Objective-C APIs, can we actually detect it and do the right thing, or
are imported APIs going to have spellings like `Awss3Rpcurl` that are
not merely ambiguous, but actively misleading?

The way I see it, at some point any convention is going to break
down. All we can do is decide which cases we care about more. Do we
want to optimize for the `XMLDocument`s of the world or the
`AwsS3RpcUrl`s?

Bottom line for me: If #2 was the convention, I'm about 90% certain I
would simply flat out ignore it when I named things, and cringe when I
had to use someone else's names. I don't think we should adopt a
naming convention that makes users cringe.

So what convention doesn't make you cringe? Would you accept any of the
others there, or is it something else?

As I mentioned to Marco, if you'd like to create an amended document
that accounts for that one, too, I'd be happy to incorporate it.
However, note that I've tried pretty hard to stay away from subjective
factors in the analysis; it would be good if you could do the same.

···

on Fri Feb 12 2016, Brent Royal-Gordon <swift-evolution@swift.org> wrote:

--
-Dave

23

Just to make things more complex, I’d like to point out I’ve used yet
another style myself in the past, #2 with elements of #1 which I’ll
refer to as #4 for the purposes of this mail. (2 << 1). Note that I
have bad grammar, thus I may mess up initialism vs acronym

The only reason the initialism/acronym distinction is important is that
the former are much more common and the latter don't have the
“mispronounced as a word instead of spelled out” problem.

vs abbreviation. Feel free to correct me.

If you are using two letter acronyms, leave the entire initialism
consistently capitalized (#1 behavior). E.g.

  func tee(ioInput: IOOutputStream) -> (IOOutputStream, IOOutputStream)

If you are using three or more letter initialism, treat them as words
for capitalization. (#2 behavior) E.g.

  func htmlDigest(for html: String) -> HtmlDigest

Visually, I find if an abbreviation is two characters long, mixed case
interferes with my ability to read it. Although the overloading is a
bit coincidental in this case, the system is not about Io the moon,
but IO the Input/Output concept.

Two letter abbreviations are short enough that at least I can easily
backtrack to say “they are not talking about some IOO concept”. The
more capital letters put in a sequence, the more you lose the ability
to disambiguate.

I’ve also found that it is very hard to turn a two letter initialism
into an acronym. In general, the pronounceable two letter
abbreviations are too short to be unambiguous when written, thus being
poor choices for naming in general. However, if we expect people to
write code on mobile phones going forward, then this may change (we
may be in trouble in general).

You also have few enough two letter initialisms that this does not in
practice run into the problems where the name of the thing is
described by multiple concatenated abbreviations, such as an HTML
DOM. Such cases of multiple two-letter abbreviations are rare enough
that there does not need to be consistency rules for them IMHO (or
shall I say, Imho)

I’ve found in practice that three letter initialisms have pros and
cons to being treated by each set of rule - but there are enough TLA
initialisms (TlaInitialism) that concatenation is more likely are
likely - and it is better to just treat the few two-letter initialisms
as special cases, and have everything else play by rule #2.

Finally, this has an interesting side benefit when you consider most
objective C packages have an initialism, abbreviation or mnemonic of
the module as a two-character prefix (even third parties often prefer
this over the recommended three-character prefix). Assuming that is
preserved on import of non-Foundation libraries, this will make such
code look far more consistent.

As I mentioned to others, if you'd like to create an amended document
that accounts for that convention, too, I'd be happy to incorporate it.
However, note that I've tried pretty hard to stay away from subjective
factors in the analysis; it would be good if you could do the same.

···

on Fri Feb 12 2016, David Waite <swift-evolution@swift.org> wrote:

--
-Dave

24

I had the same initial reaction as Dave to Jessy's suggestions, however,
the idea does kind of make sense. I'm not saying I like it, but it doesn't
bother me nearly as much as I thought it would. (I think the rule Jessy was
using would be the following.)

func hTMLDigest(for hTML: String) -> HTMLDigest

···

If an initialism is used, treat each letter as its own word.

On Fri, Feb 12, 2016 at 1:34 AM, Dave Abrahams via swift-evolution < swift-evolution@swift.org> wrote:

on Thu Feb 11 2016, Jessy Catterwaul <swift-evolution@swift.org> wrote:

> It is too complicated to have different rules when an initialism is used,
> or not.

I take it you'd be in favor of option 2 on that page, then?

> uniformResourceLocatorForPublication
> uRLForPublication

I don't understand what that example is supposed to show. No convention
ever suggested “uRL”, and I can't imagine anyone writing that. Can you?

> Sent from my iPad
>
> On Feb 12, 2016, at 12:51 AM, Dave Abrahams via swift-evolution < > > swift-evolution@swift.org> wrote:
>
> I just posted a write-up about various case conventions for initialisms:
> https://gist.github.com/dabrahams/55fc5ece355da4664730\. I was surprised
> at how it turned out, FWIW.
>
> Cheers,

--
-Dave

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

25

I take it you'd be in favor of option 2 on that page, then?

No. I am in favor of the convention I typed:
uRL

No convention ever suggested “uRL”, and I can't imagine anyone writing that.

It may be physically impossible to imagine so, at present.

Can you?

Yes. The two I use most in code are (the members are real but the types aren't):

let uRL: URL
let jSON: JSON

URL is an initialism.
JSON is a hybrid initialis-acrony-m.
What’s important is not that something is an initialism, but:
1. How it is spelled outside of code
2. Whether it is an instance, a type, a protocol that defines one member, or a protocol that defines multiple.

We encode the information of whether something is an instance, or a type, with casing. That’s ridiculous, but at least it’s easy, if your types start with English letters. To minimize cognitive load:

1. Make the first letter lowercase regardless of whether you abbreviate to initialisms.
2. Don’t start types with lowercase letters. Of Course IThings’ names get ruined. If that’s considered a problem, then we should stop using casing for type/instance, and impart better information via the IDE.

26

Addendum: another problem with convention #2 is that the rule produces "Mccall", "Iphone", and "Latex" along with "Html", all of which are less readable (for me, in context of a larger identifier like "IphoneViewController") than the convention #1 output.

(At least, my understanding of the convention #2 rule.)

···

On Feb 12, 2016, at 11:12, Jordan Rose via swift-evolution <swift-evolution@swift.org> wrote:

(re: https://gist.github.com/dabrahams/55fc5ece355da4664730\)

I am very strongly in favor of convention #1, and it comes from what we were talking about offline yesterday. This is what I do pretty much automatically when coding:

Word Lowercase "Capitalized" Uppercase
string string String STRING
Cupertino cupertino Cupertino CUPERTINO
McCall mccall McCall MCCALL
HTML html HTML HTML
iPhone iphone IPhone IPHONE
LaTeX <https://en.wikipedia.org/wiki/LaTeX&gt; latex LaTeX LATEX

(apologies to those reading this in plain text)

The important thing here is that the "capitalize" operation doesn't mess with the case of any other letters in the word. My preferred rules are then:

  • To form a type name, "capitalize" every component, then concatenate.
  • To form a value name, "lowercase" the first component, "capitalize" every other component, concatenate.

which is pretty much convention #1.

(My "capitalize" rule for coding breaks the rule for publication, in which "iPhone" would be the capitalized form. Without it, however, you end up with names like "isUsingiPhone" and "DefaultiPhoneViewController", which I agree are harder to read than "isUsingIPhone" and "DefaultIPhoneViewController".)

This isn't quite what Cocoa does (as noted by Dave, it prefers to not lowercase initialisms or acronyms in value names, leaving them all uppercase), but it's what I do in practice.

Regarding the other suggestions:

  • "HtmlString" (a type) makes me uncomfortable because there isn't a word "Html" or "html"; that is, it's not the output of any of my built-in mental operations.
  • "hTMLString" (a value) is nonsense to me; that's three words "h", "TML", and "String".
  • I really don't find "XmlRpcConnection" easier to read than "XMLRPCConnection". Easier to break up into words, yes; easier to recognize what those words are, no.

Jordan

On Feb 11, 2016, at 21:51, Dave Abrahams via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

I just posted a write-up about various case conventions for initialisms:
https://gist.github.com/dabrahams/55fc5ece355da4664730\. I was surprised
at how it turned out, FWIW.

Cheers,

--
-Dave

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

27

I think it’s important to remember that at some point acronyms are simply the enemy and that before using one in any name you should think about whether you need it. For example, in HTMLDocument it makes some sense as HTML is significantly shorter and very widely understood; you could use say, HypertextDocument since it’s not *much* longer, but it’d then actually be less specific.

AWS S3 RPC URL is a pretty extreme example, good for highlighting the problems certainly, but right off I’d say that you don’t need either AWS or RPC; the protocol is often just referred to as S3, and the RPC I believe is redundant as I’m pretty sure the S3 API isn’t used any other way. The AWS is definitely redundant if you specify URL, as URL implies the ability to specify any S3 compatible host.

So if you boil it down it could be simplified to S3URL, which isn’t pretty, but isn’t that bad any either, or you could switch for something like S3Address, and use url as a parameter name to clarify that that’s how you’re describing the address.

I know you want to use it as the extreme example that the standard will need to be able to handle, but I think that the first rule of acronyms should be that if you have more than one in a name then you’re doing it wrong. Even having a single acronym in a name should require you to stop and think whether you really need it, as in many cases you may not, or it may make more sense to move it into a parameter name.

It’s definitely a tricky one to put into a formal specification though, as it can be very subjective, and there will always be edge cases where something doesn’t quite work, but I’m not sure we should worry too much about multiple conjoined acronyms, as they should be shunned for the evil monstrosities that they are =D

···

On 12 Feb 2016, at 11:42, Brent Royal-Gordon via swift-evolution <swift-evolution@swift.org> wrote:

(Warning: I'm going to use "acronym" loosely. Sorry.)

Strong dislike for #2. I understand and accept the benefits, but I just don’t like how that looks.

Me too. I look at the examples and I'm frankly just revolted. It's a visceral reaction, something I have trouble analyzing because it's so violent. Whatever the practical benefits, it reads like a deliberate abuse of the language, like someone choosing expedience over good style, lyk sum1 doin dis bcuz its so hard 2 pres da btns.

But emotional reactions are hard to convey convincingly in text, so I'll try to distill some of it into logical argument.

Some acronym-using terms, like "XML document", are easy to turn into identifiers; others, like "AWS S3 RPC URL"*, are difficult. Option #2 handles this problem by making all acronyms equally ugly and unreadable. I don't think that's an improvement.

I especially think it's not an improvement because the resulting identifiers are so hard to read. It's true that `AwsS3RpcUrl` is technically *parseable* since the word boundaries are demarcated (well, except for that pesky `3`), but is it actually *readable* when you set eyes on it? It's not for me. My brain, being used to English, tries to read those uppercase-lowercase combinations as actual words with actual pronunciations and it just sees gibberish. Maybe that would get better with time, but this is something that every new Swift developer would go through. Capitalizing acronyms may be ambiguous sometimes, but it at least ensures that you never misread an acronym as a word.

And for those pathological cases where we think there's too much ambiguity, we *do* have another option: `AWS_S3_RPC_URL`. Swift style disfavors underscores, but it disfavors lack of clarity even more. To me, `AWS_S3_RPC_URL` is *far* clearer than either `AWSS3RPCURL` *or* `AwsS3RpcUrl`.

Incidentally, how common *are* concatenated acronyms or other forms of acronym-related ambiguity? And when it does happen in existing Objective-C APIs, can we actually detect it and do the right thing, or are imported APIs going to have spellings like `Awss3Rpcurl` that are not merely ambiguous, but actively misleading?

The way I see it, at some point any convention is going to break down. All we can do is decide which cases we care about more. Do we want to optimize for the `XMLDocument`s of the world or the `AwsS3RpcUrl`s?

Bottom line for me: If #2 was the convention, I'm about 90% certain I would simply flat out ignore it when I named things, and cringe when I had to use someone else's names. I don't think we should adopt a naming convention that makes users cringe.

(* I use the extreme "AWS S3 RPC URL" example here because the examples originally cited don't much worry me. I have no trouble reading `XMLRPC` as a single six-letter acronym and mapping it to the XML-RPC technology, the "ack" in `LAPBACK` is an abbreviation and ought to be mixed-case, and `XSLTiBook` is self-inflicted—it's not ambiguous unless you insist on violating your own API guidelines to preserve your own nonstandard capitalization.)

28

  • "hTMLString" (a value) is nonsense to me; that's three words "h", "TML", and "String”.

It was nonsense to me also. But I realized that we need to solve the problem of inconsistency, and forced myself to use it for a week.

Now, it’s not nonsense, but instead, automatic and solves all relevant casing problems.

29

Maybe that would get better with time, but this is something that
every new Swift developer would go through.

This is clearly highly subjective. Some people have no problem with it.

I strongly suspect, though I cannot prove, that it's not so much that some people have no problem with it as that some people are already acclimated to it. I would be interested to learn if the #2 voters have previous experience using that style.

Bottom line for me: If #2 was the convention, I'm about 90% certain I
would simply flat out ignore it when I named things, and cringe when I
had to use someone else's names. I don't think we should adopt a
naming convention that makes users cringe.

So what convention doesn't make you cringe? Would you accept any of the
others there, or is it something else?

I like #3, and #1 is quite acceptable as well.

I'd like to talk briefly about *why* I think #3 is okay. We do lose the "capital letter means type" cue, but I'm willing to tolerate that ambiguity. I think of types as being an abstraction of values—`numberOfRows` is some particular integer, but `Int` is the abstract concept of an integer. In a sense, a type is like a Platonic Form, and so we borrow the convention of capitalizing them to distinguish them from their concrete instances. When we want to incorporate an acronym, which is always uppercased, into the name of a concrete instance, that convention breaks down, but that's okay—it's just a convention, not an iron law of Swift identifiers.

I think that, to some extent, the decision here is a tradeoff between ambiguity and natural appearance. Perhaps I simply have a greater tolerance for ambiguity and dislike of unnatural appearance than the #2 supporters.

As I mentioned to Marco, if you'd like to create an amended document
that accounts for that one, too, I'd be happy to incorporate it.
However, note that I've tried pretty hard to stay away from subjective
factors in the analysis; it would be good if you could do the same.

I think it makes sense to try to stay away from subjective factors in your analysis, but I don't think we can make the actual decision without considering them. If you really want to make the word boundaries obvious, the best solution is to use underscores in identifiers anywhere you would normally put a space. We don't do that because of a subjective judgement that underscores in identifiers are ugly.

(If you're editing the analysis, though, one thing confuses me about #3: Why is 'Encourages “spelling” rather than “pronouncing” the initialism' only 2/3?)

···

--
Brent Royal-Gordon
Architechies

30

I should also say, sorry that my solicitation of edits for the analysis
document went out so late; that was a technical glitch. They were
composed this morning just before my connectivity dropped.

···

on Fri Feb 12 2016, Dave Abrahams <swift-evolution@swift.org> wrote:

on Thu Feb 11 2016, Dave Abrahams <swift-evolution@swift.org> wrote:

I just posted a write-up about various case conventions for initialisms:
https://gist.github.com/dabrahams/55fc5ece355da4664730\. I was surprised
at how it turned out, FWIW.

FYI, it looks like the API guidelines working group has settled on
convention #1, which is what the standard library currently does.

Coincidentally, this seems to have resulted in the fewest number of
strong objections in an area where strong opinions abound (except for
Trent—sorry, Trent).

--
-Dave

31

My only strong objection is to option #3. Option 1 is okay. I probably
should have given that a +0 instead of a -1. My preference order is more
like:

Option #2
<an inch away>
Option #1
<somewhere around the moon>
Option #3

···

On Fri, Feb 12, 2016 at 6:31 PM, Dave Abrahams via swift-evolution < swift-evolution@swift.org> wrote:

on Thu Feb 11 2016, Dave Abrahams <swift-evolution@swift.org> wrote:

> I just posted a write-up about various case conventions for initialisms:
> https://gist.github.com/dabrahams/55fc5ece355da4664730\. I was surprised
> at how it turned out, FWIW.

FYI, it looks like the API guidelines working group has settled on
convention #1, which is what the standard library currently does.

Coincidentally, this seems to have resulted in the fewest number of
strong objections in an area where strong opinions abound (except for
Trent—sorry, Trent).

--
-Dave

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
Trent Nadeau

32

I picked #2 (based on your example) but I was fine with either #1 or #2 (could have even waffled back and forth depending on the day)… so #1 would make me happy.

Did not really like #3.

And if I am happy, everyone should be happy :p

···

On 2016-02-13, at 6:31:34, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

on Thu Feb 11 2016, Dave Abrahams <swift-evolution@swift.org> wrote:

I just posted a write-up about various case conventions for initialisms:
https://gist.github.com/dabrahams/55fc5ece355da4664730\. I was surprised
at how it turned out, FWIW.

FYI, it looks like the API guidelines working group has settled on
convention #1, which is what the standard library currently does.

Coincidentally, this seems to have resulted in the fewest number of
strong objections in an area where strong opinions abound (except for
Trent—sorry, Trent).

--
-Dave

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

33

I don’t care what the heck it is as long as someone tells me whether to use userID or userId. I’ve spent too many hours obsessing over this and I still keep going back and forth. What is ID anyway? It seems like it’s both an initialism and an acronym.

I think I lean towards #2 for a simple reason: the rules are the same for initialisms, acronyms, abbreviations, words, or what have you. I just want whatever guidelines are going to allow me to pick a casing and move on with my life as soon as possible. The guideline with the fewest rules is going to be the best at that.

Tyler

···

On Feb 13, 2016, at 2:10 PM, Patrick Gili via swift-evolution <swift-evolution@swift.org> wrote:

+1 for #2, as I think this is most consistent with the rest of the naming conventions.

Cheers,
-Patrick

On Feb 12, 2016, at 12:51 AM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

I just posted a write-up about various case conventions for initialisms:
https://gist.github.com/dabrahams/55fc5ece355da4664730\. I was surprised
at how it turned out, FWIW.

Cheers,

--
-Dave

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

34

FYI,
http://news.gmane.org/find-root.php?message_id=m2twld4iax.fsf%40eno.apple.com

···

on Sat Feb 13 2016, Tyler Fleming Cloutier <swift-evolution@swift.org> wrote:

I don’t care what the heck it is as long as someone tells me whether
to use userID or userId. I’ve spent too many hours obsessing over this
and I still keep going back and forth. What is ID anyway? It seems
like it’s both an initialism and an acronym.

I think I lean towards #2 for a simple reason: the rules are the same
for initialisms, acronyms, abbreviations, words, or what have you. I
just want whatever guidelines are going to allow me to pick a casing
and move on with my life as soon as possible. The guideline with the
fewest rules is going to be the best at that.

--
-Dave

35

Strong dislike for #2. I understand and accept the benefits, but I
just don’t like how that looks.

I also don’t use #1 or #3. Instead, initialisms in my code are always
all uppercase, no exceptions.

For type names, I can’t remember a case in my code where that could
not be avoided or was too bad to read.
For local variables, methods, and functions, I try to find a name that
puts the initialism at the end of the name, e.g. let publicationURL =
document.URLForPublication

Interesting approach. If you'd like to create an amended document that
accounts for that one, too, I'd be happy to incorporate it. However,
note that I've tried pretty hard to stay away from subjective factors in
the analysis; it would be good if you could do the same.

I added this as Convention #4, along with a new paragraph at the end of the analysis:

I think I kept it objective and I hope my additions match your expectations for this document. I took the liberty to change some names in the sample code to match what I’m proposing, e.g. “urlForPublication” became “publicationURL”.

Please let me know if I should change anything.

A separate poll on the violence of peoples' negative reaction to each
choice might not be a bad idea—that stuff counts, too, as long as more
than a handful of people respond.

Agreed. Although I just want to state that mine is just a strong dislike for #2 and there is no actual violence involved in my reaction :grinning:

···

On 2016-02-12, at 17:35, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:
on Fri Feb 12 2016, Marco Masser <swift-evolution@swift.org> wrote:

In my experience, my guidelines don’t always work. Just like everyone else’s.

On 2016-02-12, at 06:51, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

I just posted a write-up about various case conventions for initialisms:
https://gist.github.com/dabrahams/55fc5ece355da4664730\. I was surprised
at how it turned out, FWIW.

Cheers,

--
-Dave

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

36

Did you realize you've dropped the mailing list from the recipient list?

···

on Fri Feb 12 2016, Xiaodi Wu <xiaodi.wu-AT-gmail.com> wrote:

Based on the examples, #2 does seem to have the most advantages. But:
what to do with vendor prefixes? Are those to be an exception?

Another tidbit: .NET seems to have its own exceptions--not sure if
there are rules for them, but just at the namespace level there's
System.IO and UIAutomationClientsideProviders, spelled as shown.

On Fri, Feb 12, 2016 at 3:07 AM, Dave Abrahams via swift-evolution > <swift-evolution@swift.org> wrote:

on Fri Feb 12 2016, Rob Mayoff <swift-evolution@swift.org> wrote:

I have been using #2 for years in many languages (including Objective-C and
more recently Swift) and much prefer it.

Incidentally, "ASCII" is one of the examples in the definition of "acronym"
in OS X's American English dictionary.

Yup, you're right.

On Thu, Feb 11, 2016 at 11:51 PM, Dave Abrahams via swift-evolution < >>> swift-evolution@swift.org> wrote:

I just posted a write-up about various case conventions for initialisms:
https://gist.github.com/dabrahams/55fc5ece355da4664730\. I was surprised
at how it turned out, FWIW.

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave

37

Based on the examples, #2 does seem to have the most advantages. But:
what to do with vendor prefixes? Are those to be an exception?

Can you some examples of a “vendor prefix?”

Another tidbit: .NET seems to have its own exceptions--not sure if
there are rules for them, but just at the namespace level there's
System.IO and UIAutomationClientsideProviders, spelled as shown.

Thanks for pointing those out.

···

on Fri Feb 12 2016, Xiaodi Wu <swift-evolution@swift.org> wrote:

On Fri, Feb 12, 2016 at 3:07 AM, Dave Abrahams via swift-evolution > <swift-evolution@swift.org> wrote:

on Fri Feb 12 2016, Rob Mayoff <swift-evolution@swift.org> wrote:

I have been using #2 for years in many languages (including Objective-C and
more recently Swift) and much prefer it.

Incidentally, "ASCII" is one of the examples in the definition of "acronym"
in OS X's American English dictionary.

Yup, you're right.

On Thu, Feb 11, 2016 at 11:51 PM, Dave Abrahams via swift-evolution < >>> swift-evolution@swift.org> wrote:

I just posted a write-up about various case conventions for initialisms:
https://gist.github.com/dabrahams/55fc5ece355da4664730\. I was surprised
at how it turned out, FWIW.

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave

38

Based on the examples, #2 does seem to have the most advantages. But:
what to do with vendor prefixes? Are those to be an exception?

Another tidbit: .NET seems to have its own exceptions--not sure if
there are rules for them, but just at the namespace level there's
System.IO and UIAutomationClientsideProviders, spelled as shown.

.NET has a specific exception for two-letter initialisms. They are all uppercase (or all lowercase at the start of a variable name). It’s in their guidelines, but I don’t think they say much about the rationale. I imagine they decided Io, Ui, etc. just don’t look right.

—CK

···

On Feb 12, 2016, at 1:39 AM, Xiaodi Wu via swift-evolution <swift-evolution@swift.org> wrote:

On Fri, Feb 12, 2016 at 3:07 AM, Dave Abrahams via swift-evolution > <swift-evolution@swift.org> wrote:

on Fri Feb 12 2016, Rob Mayoff <swift-evolution@swift.org> wrote:

I have been using #2 for years in many languages (including Objective-C and
more recently Swift) and much prefer it.

Incidentally, "ASCII" is one of the examples in the definition of "acronym"
in OS X's American English dictionary.

Yup, you're right.

On Thu, Feb 11, 2016 at 11:51 PM, Dave Abrahams via swift-evolution < >>> swift-evolution@swift.org> wrote:

I just posted a write-up about various case conventions for initialisms:
https://gist.github.com/dabrahams/55fc5ece355da4664730\. I was surprised
at how it turned out, FWIW.

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

39

(Warning: I'm going to use "acronym" loosely. Sorry.)

Strong dislike for #2. I understand and accept the benefits, but I
just don’t like how that looks.

Me too. I look at the examples and I'm frankly just revolted. It's a
visceral reaction, something I have trouble analyzing because it's
so violent. Whatever the practical benefits, it reads like a
deliberate abuse of the language, like someone choosing expedience
over good style, lyk sum1 doin dis bcuz its so hard 2 pres da btns.

But emotional reactions are hard to convey convincingly in text, so
I'll try to distill some of it into logical argument.

Some acronym-using terms, like "XML document", are easy to turn into
identifiers; others, like "AWS S3 RPC URL"*, are difficult. Option
#2 handles this problem by making all acronyms equally ugly and
unreadable. I don't think that's an improvement.

I especially think it's not an improvement because the resulting
identifiers are so hard to read. It's true that `AwsS3RpcUrl` is
technically *parseable* since the word boundaries are demarcated
(well, except for that pesky `3`), but is it actually *readable*
when you set eyes on it? It's not for me. My brain, being used to
English, tries to read those uppercase-lowercase combinations as
actual words with actual pronunciations and it just sees
gibberish. Maybe that would get better with time, but this is
something that every new Swift developer would go
through. Capitalizing acronyms may be ambiguous sometimes, but it at
least ensures that you never misread an acronym as a word.

And for those pathological cases where we think there's too much
ambiguity, we *do* have another option: `AWS_S3_RPC_URL`. Swift
style disfavors underscores, but it disfavors lack of clarity even
more. To me, `AWS_S3_RPC_URL` is *far* clearer than either
`AWSS3RPCURL` *or* `AwsS3RpcUrl`.

Incidentally, how common *are* concatenated acronyms or other forms
of acronym-related ambiguity? And when it does happen in existing
Objective-C APIs, can we actually detect it and do the right thing,
or are imported APIs going to have spellings like `Awss3Rpcurl` that
are not merely ambiguous, but actively misleading?

The way I see it, at some point any convention is going to break
down. All we can do is decide which cases we care about more. Do we
want to optimize for the `XMLDocument`s of the world or the
`AwsS3RpcUrl`s?

Bottom line for me: If #2 was the convention, I'm about 90% certain
I would simply flat out ignore it when I named things, and cringe
when I had to use someone else's names. I don't think we should
adopt a naming convention that makes users cringe.

(* I use the extreme "AWS S3 RPC URL" example here because the
examples originally cited don't much worry me. I have no trouble
reading `XMLRPC` as a single six-letter acronym and mapping it to
the XML-RPC technology, the "ack" in `LAPBACK` is an abbreviation
and ought to be mixed-case, and `XSLTiBook` is self-inflicted—it's
not ambiguous unless you insist on violating your own API guidelines
to preserve your own nonstandard capitalization.)

I think it’s important to remember that at some point acronyms are
simply the enemy and that before using one in any name you should
think about whether you need it. For example, in HTMLDocument it makes
some sense as HTML is significantly shorter and very widely
understood; you could use say, HypertextDocument since it’s not *much*
longer, but it’d then actually be less specific.

AWS S3 RPC URL is a pretty extreme example, good for highlighting the
problems certainly, but right off I’d say that you don’t need either
AWS or RPC; the protocol is often just referred to as S3, and the RPC
I believe is redundant as I’m pretty sure the S3 API isn’t used any
other way. The AWS is definitely redundant if you specify URL, as URL
implies the ability to specify any S3 compatible host.

So if you boil it down it could be simplified to S3URL, which isn’t
pretty, but isn’t that bad any either, or you could switch for
something like S3Address, and use url as a parameter name to clarify
that that’s how you’re describing the address.

I know you want to use it as the extreme example that the standard
will need to be able to handle, but I think that the first rule of
acronyms should be that if you have more than one in a name then
you’re doing it wrong.

Not everybody has your good taste :-), and acronyms/initialisms
including the compound ones, are sometimes the predefined technical
terms we have to work with, c.f. XMLRPC.

Even having a single acronym in a name should
require you to stop and think whether you really need it, as in many
cases you may not, or it may make more sense to move it into a
parameter name.

It’s definitely a tricky one to put into a formal specification
though, as it can be very subjective, and there will always be edge
cases where something doesn’t quite work, but I’m not sure we should
worry too much about multiple conjoined acronyms, as they should be
shunned for the evil monstrosities that they are =D

It's just one consideration among many.

···

on Fri Feb 12 2016, Haravikk <swift-evolution@swift.org> wrote:

On 12 Feb 2016, at 11:42, Brent Royal-Gordon via swift-evolution >> <swift-evolution@swift.org> wrote:

--
-Dave

40

Oh! Sorry, I didn't realize you were actually suggesting that; I
thought you meant it as a misinterpretation of one of the conventions
listed.

As I mentioned to Marco, if you'd like to create an amended document
that accounts for that one, too, I'd be happy to incorporate it.
However, note that I've tried pretty hard to stay away from subjective
factors in the analysis; it would be good if you could do the same.

···

on Fri Feb 12 2016, Jessy Catterwaul <swift-evolution@swift.org> wrote:

I take it you'd be in favor of option 2 on that page, then?

No. I am in favor of the convention I typed:
uRL

No convention ever suggested “uRL”, and I can't imagine anyone writing that.

It may be physically impossible to imagine so, at present.
https://www.youtube.com/watch?v=_00qkCCuWc0&feature=youtu.be&t=1156

Can you?

Yes. The two I use most in code are (the members are real but the types aren't):

let uRL: URL
let jSON: JSON

URL is an initialism.
JSON is a hybrid initialis-acrony-m.
What’s important is not that something is an initialism, but:
1. How it is spelled outside of code
2. Whether it is an instance, a type, a protocol that defines one
member, or a protocol that defines multiple.

We encode the information of whether something is an instance, or a
type, with casing. That’s ridiculous, but at least it’s easy, if your
types start with English letters. To minimize cognitive load:

1. Make the first letter lowercase regardless of whether you abbreviate to initialisms.
2. Don’t start types with lowercase letters. Of Course IThings’ names
get ruined. If that’s considered a problem, then we should stop using
casing for type/instance, and impart better information via the IDE.

--
-Dave