The Blogging Programmer's Style Guide: Quirky Software Names
It's hard to keep track of the "right" way to write and capitalize certain development product names. Here are a few tips that will help you find the right way to write any term.
The Web Dev Zone is brought to you in partnership with Mendix. Discover how IT departments looking for ways to keep up with demand for business apps has caused a new breed of developers to surface - the Rapid Application Developer.
Read the introduction to "The Blogging Programmer's Style Guide" for some background on this series.
How do I confirm the proper way to write the name of a software project/product?
Have you ever been confused about whether you need to capitalize "node.js" or whether you should write "Angular.js", "AngularJS", or just "Angular"? Project names are a common writing inconsistency I see across developer blogs. I think there are some pretty simple ground rules you can follow in these instances to help us all be clearer, more polished writers.
The Quirky Capitalization of the Software World
I remember when projects like "neo4j" and "node.js" were originally uncapitalized project titles. I wondered whether I should keep them lowercased even when they were the first word in a sentence. A lot of projects start out lowercased because of command-line typing. When Node.js and Neo4j got more popular, they had to accept their status as well-known proper nouns. Should they have been capitalized from the start?
Another common thing you see among developer tools and keywords is intra-word capitalization. NoSQL and jQuery are two good examples. Does that mean "NOSQL" is incorrect? Not quite (someone got mad at me for not capitalizing the "O" because he preferred to think of it as Not Only SQL). Are "JQuery" and "jquery" wrong? In my opinion, absolutely. I'll explain why in a minute.
These are another potential issue I see when we're talking about software tools and keywords. "Node" instead of "Node.js" is one that I worry about the most because a "node" can be a lot of things. It works out if you look at the capitalization and the context, but you should always make sure that shorthands never compromise clarity.
Also, there are two groups in the tech audience that you have to consider when writing blogs: non-native English speakers and people who are new to the development space. It's important to make sure that a wide variety of readers can easily google a term that you use.
How do we create some guidelines?
I just showed you a few examples of some possible areas for confusion, but there are many more project titles out there that you'll encounter and mention in your writing. I think it's important that blogging coders spend a second rationalizing the way they write certain terms to have the most consistent, effective, and polished content possible. Here are some pragmatic rules that I believe most developers will agree with (but feel free to voice your disagreement in the comments):
See how the creators want you to write the name.
This has to be the most obvious rule. If you've been writing AngularJS as "angular.js" because it was similar to "Node.js," you've been doing it wrong. If you go to the AngularJS homepage you'll see that they have no dot and they capitalize the "JS." Underscore.js and Backbone.js are different if you look at those pages. They both have the ".js" at the end. You can also see in the docs for all three projects that they don't mind if you just omit the ".js" (or "JS" in Angular's case).
Always respect the creator's wishes, and respect the brand. jQuery is one case where that capitalized "Q" and lowercase "j" are key parts of a very strong brand. They went through the effort of making the project and choosing a name, so you should make the effort to write it correctly. Anytime you aren't sure about the way to write a project's name, go to the homepage or repo's readme page.
Write the proper long-form name the first time you use a word in a post.
One other guideline you should follow in your articles is to write the unabridged, proper form of a project name or keyword when you're using it for the first time in a post. It's generally acceptable to say "Node", "Rails", or "Mongo" in your posts, but the first time you mention them in each blog post, you should establish that you're talking about "Node.js", "Ruby on Rails", or "MongoDB". This is also a good habit for acronyms. Write the full term (ex. software-defined networking) and then use the acronym throughout the rest of the post (SDN).
Here's a list of the more common tech projects / terms and their proper usage:
Not Angular.js. "Angular" is acceptable shorthand.
Not BackboneJS. "Backbone" is acceptable shorthand.
Not github. Not Github.
Not java. Not JAVA.
Not JQuery. Not jquery.
Not KnockoutJS. "Knockout" is acceptable shorthand.
Not neo4j. "Neo" is acceptable shorthand.
Not node.js. "Node" is acceptable shorthand.
Not Map/Reduce. Not Map Reduce.
Not Mongodb. Not mongodb. "Mongo" is acceptable shorthand.
Not Rest. Not restful.
Rails or Ruby on Rails
RoR works too, but define it as "Ruby on Rails" before you use abbreviations.
Not UnderscoreJS. "Underscore" is acceptable shorthand.
Capitalize Every Acronym
URL not url
There's a lot of odd capitalization configurations that creators will use, so be prepared for variability. If there are any more particularly confusing, common terms that you'd like me to add to this list, leave a comment and I may include it.