[swift-evolution] Analysis of case conventions for initialisms

Brent Royal-Gordon brent at architechies.com
Fri Feb 12 05:42:47 CST 2016

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

Brent Royal-Gordon

More information about the swift-evolution mailing list