Analysis of case conventions for initialisms


(Dave Abrahams) #1

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


(Brent Royal-Gordon) #2

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.

This is perhaps not a practical answer, but honestly, I'm having trouble thinking of a case where a variable name that's an initialism is a *good* name. Initialisms often make sense as types—HTML, URL, UUID, etc. But as variable names, they tend to be overly vague. For instance, in the example you give:

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

`url` is not really a very descriptive name for the parameter; it would probably be better as `destinationURL` or `fileURL` or `documentURL`. You might even want to drop the `URL` from the end of those, making `destination`, `file`, or `document`. The name `url` is about as descriptive as `block` would be for the last parameter.

(That's not to say I haven't done this; I certainly have. But I'm thinking that maybe the code where I did it wasn't as good as it could have been.)

So I wonder if we shouldn't instead guide that initialisms should not appear at the beginning of variable names. You should name your variables (and properties) for their semantic, not their type.

If initialisms don't appear at the beginning of variable names, then you can distinguish between types and variables by capitalization. That leaves only the word boundary issues, which I think we can live with.

···

--
Brent Royal-Gordon
Architechies


(Jarod Long) #3

+1 for 2. I've used all three of these conventions at different times, and I've had noticeably less friction with option 2.

Jarod

···

On Feb 11, 2016, at 21:51, Dave Abrahams via swift-evolution <swift-evolution@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@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Jessy) #4

It is too complicated to have different rules when an initialism is used,
or not.

uniformResourceLocatorForPublication
uRLForPublication

···

Sent from my iPad

On Feb 12, 2016, at 12:51 AM, Dave Abrahams via swift-evolution < swift-evolution@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@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

On Friday, February 12, 2016, Dave Abrahams via swift-evolution < swift-evolution@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@swift.org <javascript:;>
https://lists.swift.org/mailman/listinfo/swift-evolution


(Rob Mayoff) #5

I have been using #2 for years in many languages (including Objective-C and
more recently Swift) and much prefer it.

Incidentally, "ASCII" is one of the examples in the definition of "acronym"
in OS X's American English dictionary.

···

On Thu, Feb 11, 2016 at 11:51 PM, Dave Abrahams via swift-evolution < swift-evolution@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.


(David Waite) #6

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@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@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Jordan Rose) #7

(re: https://gist.github.com/dabrahams/55fc5ece355da4664730)

I am very strongly in favor of convention #1, and it comes from what we were talking about offline yesterday. This is what I do pretty much automatically when coding:

Word Lowercase "Capitalized" Uppercase
string string String STRING
Cupertino cupertino Cupertino CUPERTINO
McCall mccall McCall MCCALL
HTML html HTML HTML
iPhone iphone IPhone IPHONE
LaTeX <https://en.wikipedia.org/wiki/LaTeX> latex LaTeX LATEX

(apologies to those reading this in plain text)

The important thing here is that the "capitalize" operation doesn't mess with the case of any other letters in the word. My preferred rules are then:

  • To form a type name, "capitalize" every component, then concatenate.
  • To form a value name, "lowercase" the first component, "capitalize" every other component, concatenate.

which is pretty much convention #1.

(My "capitalize" rule for coding breaks the rule for publication, in which "iPhone" would be the capitalized form. Without it, however, you end up with names like "isUsingiPhone" and "DefaultiPhoneViewController", which I agree are harder to read than "isUsingIPhone" and "DefaultIPhoneViewController".)

This isn't quite what Cocoa does (as noted by Dave, it prefers to not lowercase initialisms or acronyms in value names, leaving them all uppercase), but it's what I do in practice.

Regarding the other suggestions:

  • "HtmlString" (a type) makes me uncomfortable because there isn't a word "Html" or "html"; that is, it's not the output of any of my built-in mental operations.
  • "hTMLString" (a value) is nonsense to me; that's three words "h", "TML", and "String".
  • I really don't find "XmlRpcConnection" easier to read than "XMLRPCConnection". Easier to break up into words, yes; easier to recognize what those words are, no.

Jordan

···

On Feb 11, 2016, at 21:51, Dave Abrahams via swift-evolution <swift-evolution@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@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Marco Masser) #8

Strong dislike for #2. I understand and accept the benefits, but I just don’t like how that looks.

I also don’t use #1 or #3. Instead, initialisms in my code are always all uppercase, no exceptions.

For type names, I can’t remember a case in my code where that could not be avoided or was too bad to read.
For local variables, methods, and functions, I try to find a name that puts the initialism at the end of the name, e.g. let publicationURL = document.URLForPublication

In my experience, my guidelines don’t always work. Just like everyone else’s.

···

On 2016-02-12, at 06:51, Dave Abrahams via swift-evolution <swift-evolution@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@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Scott James Remnant) #9

Strong preference for #1

···

On 2016-02-12 05:51:32 +0000, Dave Abrahams via swift-evolution said:

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 Abrahams) #10

FYI, it looks like the API guidelines working group has settled on
convention #1, which is what the standard library currently does.

Coincidentally, this seems to have resulted in the fewest number of
strong objections in an area where strong opinions abound (except for
Trent—sorry, Trent).

···

on Thu Feb 11 2016, Dave Abrahams <swift-evolution@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.

--
-Dave


(Howard Lovatt) #11

+1 #2

  -- Howard.

···

On 12 February 2016 at 16:51, Dave Abrahams via swift-evolution < swift-evolution@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@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Patrick Gili) #12

+1 for #2, as I think this is most consistent with the rest of the naming conventions.

Cheers,
-Patrick

···

On Feb 12, 2016, at 12:51 AM, Dave Abrahams via swift-evolution <swift-evolution@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@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Dave Abrahams) #13

It is too complicated to have different rules when an initialism is used,
or not.

I take it you'd be in favor of option 2 on that page, then?

uniformResourceLocatorForPublication
uRLForPublication

I don't understand what that example is supposed to show. No convention
ever suggested “uRL”, and I can't imagine anyone writing that. Can you?

···

on Thu Feb 11 2016, Jessy Catterwaul <swift-evolution@swift.org> wrote:

Sent from my iPad

On Feb 12, 2016, at 12:51 AM, Dave Abrahams via swift-evolution < > swift-evolution@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


(Jonathan Tang) #14

+1 for #2, which is also what Java and Google code conventions do. It
looks awkward at first, but being able to distinguish word boundaries is
surprisingly important. Tech is rife with initialisms; you could
realistically have a class or constant like AWSS3RPCURL where every single
letter is part of an initialism.

···

On Thu, Feb 11, 2016 at 10:52 PM, Brent Royal-Gordon via swift-evolution < swift-evolution@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.

This is perhaps not a practical answer, but honestly, I'm having trouble
thinking of a case where a variable name that's an initialism is a *good*
name. Initialisms often make sense as types—HTML, URL, UUID, etc. But as
variable names, they tend to be overly vague. For instance, in the example
you give:

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

`url` is not really a very descriptive name for the parameter; it would
probably be better as `destinationURL` or `fileURL` or `documentURL`. You
might even want to drop the `URL` from the end of those, making
`destination`, `file`, or `document`. The name `url` is about as
descriptive as `block` would be for the last parameter.

(That's not to say I haven't done this; I certainly have. But I'm thinking
that maybe the code where I did it wasn't as good as it could have been.)

So I wonder if we shouldn't instead guide that initialisms should not
appear at the beginning of variable names. You should name your variables
(and properties) for their semantic, not their type.

If initialisms don't appear at the beginning of variable names, then you
can distinguish between types and variables by capitalization. That leaves
only the word boundary issues, which I think we can live with.

--
Brent Royal-Gordon
Architechies

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Dave Abrahams) #15

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.

This is perhaps not a practical answer, but honestly, I'm having
trouble thinking of a case where a variable name that's an initialism
is a *good* name. Initialisms often make sense as types—HTML, URL,
UUID, etc. But as variable names, they tend to be overly vague. For
instance, in the example you give:

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

`url` is not really a very descriptive name for the parameter; it
would probably be better as `destinationURL` or `fileURL` or
`documentURL`. You might even want to drop the `URL` from the end of
those, making `destination`, `file`, or `document`. The name `url` is
about as descriptive as `block` would be for the last parameter.

Yeah, it's a poor name, but people do it anyway, and there are still
plenty of legitimate uses for names *starting* with "url"

(That's not to say I haven't done this; I certainly have.

See, there?

But I'm thinking that maybe the code where I did it wasn't as good as
it could have been.)

So I wonder if we shouldn't instead guide that initialisms should not
appear at the beginning of variable names. You should name your
variables (and properties) for their semantic, not their type.

If initialisms don't appear at the beginning of variable names, then
you can distinguish between types and variables by
capitalization. That leaves only the word boundary issues, which I
think we can live with.

It's an interesting angle, but does banning “urlToOpen” or “asciiSpace”
(pick your favorite spelling convention) really make sense?

···

on Thu Feb 11 2016, Brent Royal-Gordon <swift-evolution@swift.org> wrote:

--
-Dave


(Dave Abrahams) #16

I have been using #2 for years in many languages (including Objective-C and
more recently Swift) and much prefer it.

Incidentally, "ASCII" is one of the examples in the definition of "acronym"
in OS X's American English dictionary.

Yup, you're right.

···

on Fri Feb 12 2016, Rob Mayoff <swift-evolution@swift.org> wrote:

On Thu, Feb 11, 2016 at 11:51 PM, Dave Abrahams via swift-evolution < > swift-evolution@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.

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave


(Xiaodi Wu) #17

Based on the examples, #2 does seem to have the most advantages. But:
what to do with vendor prefixes? Are those to be an exception?

Another tidbit: .NET seems to have its own exceptions--not sure if
there are rules for them, but just at the namespace level there's
System.IO and UIAutomationClientsideProviders, spelled as shown.

···

On Fri, Feb 12, 2016 at 3:07 AM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

on Fri Feb 12 2016, Rob Mayoff <swift-evolution@swift.org> wrote:

I have been using #2 for years in many languages (including Objective-C and
more recently Swift) and much prefer it.

Incidentally, "ASCII" is one of the examples in the definition of "acronym"
in OS X's American English dictionary.

Yup, you're right.

On Thu, Feb 11, 2016 at 11:51 PM, Dave Abrahams via swift-evolution < >> swift-evolution@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.

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(James Hillhouse IV) #18

+1 for #2. I like 2's clearer word boundaries and continuation of Swift's name type convention.

Jim

···

On Feb 11, 2016, at 21:51, Dave Abrahams via swift-evolution <swift-evolution@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@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Brent Royal-Gordon) #19

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

···

--
Brent Royal-Gordon
Architechies


(David Waite) #20

Just realized that in trying to clarify the tee function I added a redundant Output to the type names. I should not use abbreviations before having coffee.

-DW

···

On Feb 12, 2016, at 8:16 AM, David Waite <david@alkaline-solutions.com> wrote:

  func tee(ioInput: IOOutputStream) -> (IOOutputStream, IOOutputStream)