Capitalization of Initialisms

January 4, 2009

Initialisms like “JMS”, “XML”, and “TCP” can be written one of two ways in camel case. They can either be treated like an initialism (all upper-case) or like a word (initial cap only). For example:

SetTCPParameters() vs. SetTcpParameters()
ForwardSDKCommand() vs. ForwardSdkCommand()

There are several problems with the all-caps approach:

  1. Several initialisms in a row will run into each other, such as XMLHTTPRequest. In fact that object uses lower-case for one of XML or HTTP. Do you remember which one? Is it XmlHTTPRequest or XMLHttpRequest? Had they used initial-caps, it would have been clear: XmlHttpRequest. Same with Java’s HttpURLConnection, where they made different choices about which word to capitalize.

  2. If the word following the initialism is a regular word, its first letter, being capitalized, looks like it’s part of the initialism. In Java they sometimes tried to fix this by making that letter lower case (Math.IEEEremainder()), but did so inconsistently (SQLData).

  3. When the initialism is at the start of the identifier, it’s difficult to automatically convert it from upper case to lower case. For example, the class JmsTemplate can be used to create local variable jmsTemplate or member variable mJmsTemplate. Those conversions would be difficult and bug-prone to do if the three identifiers were JMSTemplate, jmsTemplate, and mJMSTemplate.

  4. Similarly, it’s difficult and bug-prone to automatically convert identifiers to the underscore style. XmlHttpRequest is trivial to convert to XML_HTTP_REQUEST (e.g., for a constant), but XMLHTTPRequest can’t be converted automatically at all, forcing mixed-use.

  5. Some words, like laser and scuba, transition slowly from being an acronym to being a word. Different people may treat them differently, leading to different uses. Using initial caps avoids this ambiguity.

  6. All-caps text is more difficult to read than mixed-cap text. The letters “XML” make a box, as do the letters “HTTP”. But the letters “Xml” have a dip at the middle of the top, and “Http” has a descender at the end and a hole at the top-right. These different shapes are easier for our eyes to pick out.

To avoid the above problems, just use initial caps for all segments, whether words or initialisms.