[swift-evolution] Analysis of case conventions for initialisms

[David Waite]

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

-DW

> On Feb 11, 2016, at 10:51 PM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
> 
> 
> I just posted a write-up about various case conventions for initialisms:
> https://gist.github.com/dabrahams/55fc5ece355da4664730.  I was surprised
> at how it turned out, FWIW.
> 
> Cheers,
> 
> -- 
> -Dave
> 
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 4139 bytes
Desc: not available
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160212/708f5689/attachment.p7s>