[swift-evolution] Analysis of case conventions for initialisms

[Haravikk]

> On 12 Feb 2016, at 11:42, Brent Royal-Gordon via swift-evolution <swift-evolution at 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.)

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