Javascript Naming Conventions, Coding Guidelines and Best Practices

Thanks for the post. I couldn't find a document regarding javascript naming conventions, either.

Oops, something went wrong. Here's my full reply:

While I do agree with some of your points, I do not agree with all of them. I've seen some bad code in my life, and not only in the JavaScript language. However, when someone (usually a classmate) asks something about his or her code (they are good at other stuff, I'm good at coding) I usually give it a glance and come up with one or more of the following:

1) I agree about the variable prefixes. Though JavaScript is loosely typed, forgetting what type a variable should be, could create all sorts of nasty critters in your script.

Your prefixes:

'n': Number
's': String
'a': Array
'o': Object
'b': Boolean

However, you forgot a few:

'f': Function (for callback)
'v': Variable (for accepting multiple types)
'e': Event (for on* events)
'n': Node/Element (for handling DOM nodes/elements)

2) There is no excuse for old-style global variables.

If you put your functions in one (or a few) objects with good, descriptive and relatively unique names, you can access your functions like: 'foo.bar();' or 'foo.bars.get();' and it's relatively hard to interfere with other scripts (added in the future, perhaps).

Also, if one or more variables are needed by different functions, attach them to your master object, etc 'foo.variableobject = {};' instead of 'document.variableobject', wich it would get attached to otherwise. The only name that should be visible from the document level is the name of the object containing the functions; in this example: 'foo'.

As such, there is no real need to differentiate between global or local variables using a 'g' or 'm' prefix, since you always call global variables with the prefix 'foo.' and local variables as is.

There are ways to make functions inside an object private (by putting it inside a function object and immediately calling it), but that makes an unreadable mess of the code.

And it's not needed: If a function that's called by another function must never, ever be called outside of the function's scope, then usually (but not always) there is something wrong. In such a case, you should refactor the offending code instead of making the function private by prefixing it with '_'.

However, there is a case where I could see it useful: if you declare a 'initialization' function (or something similar) and need to run it immediately. In such a case, it could be unwise to have it possibly be called again in the script by some intern, so you could notate such a function like this:

var lib = {
_init: function() {
// code here
}()
};


Call it, and it will auto-selfdestruct. In such a case, it's a good idea to prefix it with '_', because without further work, it will still show up in the dom (with the value 'null'). Do remember, however, that the 'lib' object isn't accesible yet since it hasn't fully been parsed yet. I believe you can access the functions above (that have been parsed) by using the 'this.' keyword, but I'm not completely sure about that.

3) On the same token, variables should -of course- always, always be initialized before using. But I'm sure you agree.

4) I disagree with you on the third point; the capitalization of the first letter: 'Foo();' is usually used exclusively on Constructors: 'var x = new Foo();'. To use it on class names as well may confuse things. If you really need to differentiate, use the prefix 'c' for classes.

5) In a project where object notation is not possible (eg: a large, existing project you need to do maintenance on), I wholly agree with CamelCasing the functions names. It's more readable then using underscores (eg: 'CamelCaseName' instead of 'camel_case_name'). However, when using object notation, it is not needed, provided you use short, descriptive names:

var lib = {
age: {
get: function() {},
set: function() {}
},
address: {
get: function() {},
set: function() {},
merge: function() {}
}
};


Since you need to access the functions by object notation, it's clear what they do: 'lib.age.get();' gets an age, and 'var result = lib.address.merge(one, two);' merges two addresses into one and passes the result back.

6) As for the rest: I agree with you, but single quotes is not necessary. Personally, I use double quotes, but single quotes are just as good. There is no real speed difference between the two (it's not PHP you know!). HTML manipulation should be done through the DOM, so you don't need to escape anything (usually). However, wichever you choose, single quotes or double quotes, do use them consistently throughout a script.

7) A CDATA tag is usually not needed, since inline scripting is bad practice anyway. Always use external JS files. In the case that you really can't, you don't need a CDATA tag either, since browser that don't support javascript have been dead for the last 10+ years (Netscape 4, anyone?). In the case of XML, the CDATA tag is indeed necessary. In that case, use it.

8) When working alone on a project, indentation doesn't really matter. But when there's a possibility of one or more other developers coming on board on the project, it becomes essential. Everyone has his or her own style and the only way to facilitate that is to use tabs. Most editors can't (reliably) convert 2 to 4 spaces or 4 to 6 or whatever the developer's preference is. They can, however, convert a tab to exactly the amount of spaces the developer wants, and save them back as tabs.

This way, the code is easily readable and editable for every developer, even though some might use one space, 6 space or 256 spaces as indentation.

I believe (it has been some time since I've viewed code that way) that it does make matters more difficult if you view the code in a linux text editor (for example through putty on a live server), but in real-world situations such old-school methods aren't neccesary. This is also the reason that a 40 character line limit is not done nowadays. Don't rape up your functions and contenate substrings because you really need to stay within those 40 characters, it makes code unreadable in modern editors.

9) Functions should have no space after the function name and before the '()'. When calling a function, however, there should be a space.

If/else loops, for loops, etc. should always have a space before the '(' and after the
')'. In both functions and loops, the trailing '{' should be on the same line, and the closing '}' should be on the start of a newline, at the same indentation as the declaration.

This way, constant variables inside the function can be 'hung' on the top of the function (without a empty line first), and a 'return' or 'throw' can be fixed to the bottom of the function. If there is no 'return' or 'throw' at the end of the functions, the last line should be an empty one (except for the indentation, ofcourse). It's the same with the first line if there are no global variables used in the function.

This increases readability about what a function does and if it does or should return a value or not.

10) Documentation should not be used sparingly. However, the words that make up the documentation should. I've seen code where a wannabe-pocketbook-writer declared a 50-line commentblock for a simple 'alert();'. Really. I'm not kidding here.

It's best to generate documentation with appropriate tools (there are a few available, search google for 'em) and/or write documentation in that style. This way, it can be machine-read, parsed and you can do all kinds of nice stuff with it (generate diagrams, a help library etc).

Hoewever, the documentation comments should be in a block, like: '/** whatever **/'. If you need, for whatever reason, additional documentation inside the function, always use '// whatever' lines after the line number you are writing about (with a space between it and the comment ofcourse). But please, do use these sparingly.

If you need a 'post-it note' from yourself to yourself (about eg. something you really need to change today) and your desk is full ;), then use a '/* NOTE: whatever */' styled commentblock. If you temporarily edit out a code block, then also use the '/* */' style tags. Most editors display these in a different color then the regular '/** **/' blocks (or you can set your editor to).

11) Nowadays, most Javascript developers without expensive integrated IDE's (I like the lean Notepad++ myself) need a way to debug their JS and easily traverse the DOM. The answer has come (atleast for Gecko variants) in Firebug. I agree with others that it's a wonderful plugin for Firefox, but please, Please don't forget to remove 'console.whatever();' calls when deploying the software (or atleast use a 5 lined Firebug Lite script to reset those commands to empty objects). I have seen web applications break and abort on simple 'console.log();' commands, since Firebug is usually not installed by the end-user.

You don't want anything related to debugging in your deployed application!

12) Instead of using old-style Constructors, use literals wherever possible. This increases readability a thousandfold. For example, dont do this:

var newfunc = new Function() {};
var newobj = new Object() {};
var newarr = new Array() [];
var newreg = new Regexp("");


Instead, do this:

var newfunc = function() {};
var newobj = {};
var newarr = [];
var newreg = //;


This counts in particular for regular expressions. Regular Expressions are good. Regular Expressions are fun. But, as said above, use the object literal!!

When you get to sufficiently complex regexp functions -in a application you barely know- and you need to understand the regular expressions used, you really don't want to struggle to all escapes because someone used the string method to instantiate the Regexp object: 'var foo = new Regexp();'. When you use the literal: 'var foo = /regexphere/', it's much more readable.

13) Generating code on the fly is a bad idea. Eval(); is a bad idea (except for JSON operations). Generating code from pre-regexped strings, regexping them on the fly back to a readable piece of code and eval()ing that code is a horrendously stupid idea. I've seen someone do it once. He defended himself with: "I don't want anyone seeing my code". Ugh.

If you really need to hide your code before deployment, use an obfuscation (and usually compression) tool. This has the added effect of minimizing the kB footprint of your code.

But when you program in javascript, you should realize your code is always visible, even if it is obfuscated, because it's interpreted at run-time. It's the nature of the beast, and if you don't like it then don't code in JavaScript!

A few simple search and replace regexps and a minimized piece of code is back to something readable (even if the function names and variables are named 'aa', 'ab', 'ac' etc).

14) It's generally not a good idea to extend the default structures. Yes, object doesn't have a '.merge();' function, but that doesn't mean you should put it in there. It's quite possible (even very likely!) other scripts may break. This counts in particular for objects! Almost everythin in JavaScript is an object; it isn't a 'object oriented language' for nothing. If you tamper with the base Object, you tamper with the whole foundation of the language. Not a good thing.

If you really need a 'object.merge();' function, make a function in your library object, like: 'lib.object.merge();'. It isn't that much different in syntax, but atleast you show respect for the language and play nice with other scripts.

That goes for anything, ofcourse. Keep it in your library object!.

Well, uhm, that's how I think about it... *grin*.

... my post does seem a bit... preachy. But it wasn't meant that way. :)
It's just horrible that JavaScript is always mentioned in the same sentence as the words 'foul' 'soup' and 'messy', usually by people who code without any conventions.

So yeah, thumbs up for your article. Everybody who uses JavaScript in a strict, sensible way is a good person in my book.

hi raul.

i really agree with your Trys.
i want make korean javascript dev guide line for me or for our company.
and i want research guide lines .
can i translate this document to korean? if you approve , i'll send the url.
thanks.

I can always tell someone who's never really programmed in a dynamic (not "loosly", whatever that means) typed language. They look for all sorts of ways of assigning a type to a variable. I've seen variables with the type they want in them (userNameString, ageInteger), I've seen, like you've done, with prefixes (sUserName, iAge); all attempts to make the dynamic language be more like the language they'd prefer to be using (usually Java, VB, or c#).

What you need to understand is type isn't important in a dynamically-typed language, like it is in a statically typed language. If your method/function needs the user name, which you will display as text to the user, why do you care if it's a string or not? Why this obsession with the type? All you care about is that it can become a string when needed; so you care about the interfaces the object responds to, not what type it is, or more specifically the methods it has.

The power of a dynamically typed language has nothing to do with the fact that you don't have to type the "type", but rather its ability to allow objects to automatically implement interfaces, to be dynamically changed at runtime, meta-programming, and the ability to use either prototype or class-style structure.

Look at any of the advanced javascript libraries (jQuery or prototype for examples), and you'll see it doesn't look just like Java but with var instead of int. It's a totally different paradigm, one that is very powerful, and worth the time to learn correctly.

So please, leave the type information off of the variable names, you're making the Ruby/Python/Perl/Smalltalk/Javascript people laugh at you.