[swift-evolution] Analysis of case conventions for initialisms

[Dave Abrahams]

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

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

-- 
-Dave