Case Conventions for Initialisms

CaseConventionsForInitialisms.md

Case Conventions for Initialisms

We've discussed three possibile conventions for the case of initialisms. This document examines the tradeoffs.

The choices

1. func htmlDigest(for html: String) -> HTMLDigest

If the initialism starts a non-type name, downcase it; otherwise, upcase it.

This is existing practice in the Swift standard library.

let asciiPlus = "+".utf8.first!
let titleHasMultipleWords = title.utf16.contains(asciiSpace)

let hasURL = page.webAddress != nil
let heading = "<h1>\(title.htmlEncode(asciiOnly: true))</h1>"

let urlForPublication = URL("http://forkjoin.net/\(fork)/knife/spoon")
document.urlForPublication = urlForPublication

if let validated = HTMLValidator(page.webAddress).validHTML {
  post(XMLRPCRequest(.validated))
}

• Initialisms in public APIs appear as in ordinary text.
• All initialisms in code appear as in ordinary text.
• Makes word boundaries obvious.
• [⅓] Encourages “spelling” rather than “pronouncing” the initialism.
• Minimizes possibility of name collision
• Can distinguish type names from others on sight.

2. func htmlDigest(for html: String) -> HtmlDigest

Treat whole the initialism like an ordinary word

This was suggested by Charles Kissinger on swift-evolution and then echoed by Trent Nadeau. It is also existing practice in .NET.

let asciiPlus = "+".utf8.first!
let titleHasMultipleWords = title.utf16.contains(asciiSpace)

let hasUrl = page.webAddress != nil
let heading = "<h1>\(title.htmlEncode(asciiOnly: true))</h1>"

let urlForPublication = Url("http://forkjoin.net/\(fork)/knife/spoon")
document.urlForPublication = urlForPublication

if let validated = HtmlValidator(page.webAddress).validHtml {
  post(XmlRpcRequest(.validated))
}

• Initialisms in public APIs appear as in ordinary text.
• All initialisms in code appear as in ordinary text.
• Makes word boundaries obvious.
• Encourages “spelling” rather than “pronouncing” the initialism.
• Minimizes possibility of name collision
• Can distinguish type names from others on sight.

3. func HTMLDigest(for html: String) -> HTMLDigest

If the initialism starts a local variable name, downcase it; otherwise, upcase it

IIUC, this is existing practice in Cocoa.

For example,

let asciiPlus = "+".UTF8.first!
let titleHasMultipleWords = title.UTF16.contains(ASCIISpace)

let hasURL = page.webAddress != nil
let heading = "<h1>\(title.HTMLEncode(ASCIIOnly: true))</h1>"

let urlForPublication = URL("http://forkjoin.net/\(fork)/knife/spoon")
document.URLForPublication = urlForPublication

if let validated = HTMLValidator(page.webAddress).validHTML {
  post(XMLRPCRequest(.validated))
}

• Initialisms in public APIs appear as in ordinary text.
• All initialisms in code appear as in ordinary text.
• Makes word boundaries obvious.
• [⅔] Encourages “spelling” rather than “pronouncing” the initialism.
• Minimizes possibility of name collision.
• Can distinguish type names from others on sight.

Analysis

Under convention #1 you can easily tell by looking at a name whether it denotes a type. Whether or not that ability is valuable can of course be debated: it's possible that our case convention's only value is in reducing name collisions. In this convention, it's possible to misread url as “earl”, but at least URL will not be misread.

Convention #2 preserves most of the benefits of convention #1, and avoids the problem of word boundaries inherent in names like XMLRPC, XSLTiBook (is that “XSLT iBook” or “XSL TiBook”?) and LAPBACK (“LAPB” + “ACK”). It's also simple: arguably, no special rules are required for initialisms at all under this convention. However, what it really means to UpperCamelCase or lowerCamelCase an initialism is open to wide interpretation, so we'd probably need to say something explicit anyway. Under this convention it's possible to misread both url and Url as “earl.”

Under convention #3, the word boundary problem is back, and you can no longer tell by looking at a name that it denotes a type. The case conventions still serve to minimize collisions between types and everything else in most cases—but when a name starts with an initialism, that benefit is lost. Like the other conventions, it does not achieve consistency among all uses of a given initialism, because the standard practice (and one that is encouraged by our documentation, sample code, and WWDC presentations) is to use lower-case for initialisms at the beginning of parameter and local variable names:

func saveToURL(
  _ url: NSURL,
//  ^^^
  forSaveOperation saveOperation: UIDocumentSaveOperation,
  completionHandler completionHandler: ((Bool) -> Void)?)