[swift-evolution] Analysis of case conventions for initialisms

[Dave Abrahams]

on Fri Feb 12 2016, Brent Royal-Gordon <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. 

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.

-- 
-Dave