[swift-evolution] Analysis of case conventions for initialisms

[Dave Abrahams]

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

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

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.

-- 
-Dave