Code Advice #4: Don't capitalize acronyms!

WARNING: This blog entry was imported from my old blog on blogs.sun.com (which used different blogging software), so formatting and links may not be correct.

(See intro for a background and caveats on these coding advice blog entries.)

Remember how your ${NATIVE_LANGUAGE} teacher taught you to capitalize your acronyms? Please unlearn it. Thanks.

Seriously though... when you're writing code, you're not writing English. It makes perfect sense to choose symbol names that read well in your preferred human language. But CamelCase, the preferred capitalization scheme in Java code, is not proper English capitalization either. So don't carry over the acronym habit from English.

For example, use HtmlDocument instead of HTMLDocument. Use CssParser, not CSSParser.
Unfortunately, many existing APIs violate this rule. Even the JDK has many violations - acronyms like IO, UTF, EOF, XML, SQL, HTTP, URL and URI abound. However, I think the trend is towards uncapitalized acronyms in newer classes going through the JSR process.

So why precisely should acronyms not be capitalized? For readability reasons. The acronyms are treated as words, not as individual letters, so when you're scanning a CamelCase word you can quickly see that HtmlDocument contains the words "Html" and "Document". So it's easier to visually scan, and I think it just looks better.

Unfortunately, it may be tricky to rename existing classes in your code. If you use CVS, changing class names that vary only in capitalization will confuse CVS on some platforms. On Windows two filenames are considered identical if they only vary in case.

Eof.